> ## Documentation Index
> Fetch the complete documentation index at: https://intervyo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate requests against the intervyo.ai REST API with an x-api-key header.

Every API request authenticates with a workspace-scoped **API key** sent in the `x-api-key` header. Keys are created in the team dashboard and are prefixed `iv_live_`.

## Get an API key

<Steps>
  <Step title="Open Developer settings">
    Sign in, then **Settings → Developer → API keys** inside your workspace.
  </Step>

  <Step title="Open API Keys">
    In the team dashboard, go to **Developer → API Keys**.
  </Step>

  <Step title="Create a key">
    Click **New API key**. Name it for the integration that'll use it (e.g. `ats-sync-prod`, `embed-widget-staging`) so audit logs are interpretable.
  </Step>

  <Step title="Create a key">
    Click **New API key**. Name it for the integration that will use it (e.g. `ats-sync-prod`, `embed-widget-staging`) so audit logs stay readable.
  </Step>

  <Step title="Pick the smallest scope that works">
    Scopes are additive. Hand the key only the surface it needs — a key that just creates sessions doesn't need read access to participants.

    | Scope                | What it allows                                      |
    | -------------------- | --------------------------------------------------- |
    | `sessions:read`      | Read sessions, scorecards, transcripts, recordings. |
    | `sessions:write`     | Create + cancel sessions.                           |
    | `participants:read`  | Read participants and resume data.                  |
    | `participants:write` | Create + update participants.                       |
    | `templates:read`     | Read evaluation templates + stages.                 |
    | `webhooks:write`     | Manage webhook endpoints.                           |
  </Step>

  <Step title="Pick the smallest scope that works">
    Scopes are additive — grant a key only the surface it needs.

    | Scope                                    | Grants                                     |
    | ---------------------------------------- | ------------------------------------------ |
    | `candidates.read` / `.write` / `.delete` | Read / create-update / delete participants |
    | `interviews.read` / `.write`             | Read / create sessions and agent profiles  |
    | `evaluation_templates.read` / `.write`   | Read / manage evaluation templates         |
    | `evaluation_stages.read` / `.write`      | Read / manage stages                       |
    | `programs.read` / `.write`               | Read / manage programs and enrollments     |
  </Step>

  <Step title="Copy the secret">
    The full key is shown **once**. Copy it to your secret manager immediately. You can rotate it later but you can't recover the plaintext.
  </Step>

  <Step title="Copy the secret">
    The full key (`iv_live_…`) is shown **once**. Copy it into your secret manager immediately — you can rotate it later, but you can't recover the plaintext.
  </Step>
</Steps>

## Authorize a request

Send the key in the `x-api-key` header:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.intervyo.ai/api/v1/sessions" \
    -H "x-api-key: iv_live_your_key_here"
  ```

  ```ts TypeScript theme={null}
  await fetch("https://www.intervyo.ai/api/v1/sessions", {
    headers: { "x-api-key": process.env.INTERVYO_API_KEY! },
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://www.intervyo.ai/api/v1/sessions",
      headers={"x-api-key": os.environ["INTERVYO_API_KEY"]},
  )
  ```
</CodeGroup>

<Warning>
  **Never** ship API keys to a browser, mobile bundle, or any client surface — a key grants workspace-wide access on its scopes. Call the API from your own backend, or use the [embed widget](/en/guides/embed-widget), which exchanges short-lived participant tokens instead.
</Warning>

## Session (cookie) auth

Requests made from a signed-in dashboard session can authenticate with cookies instead of a key. For those calls, pass your team slug as the `accountSlug` query parameter so the API can resolve the workspace:

```bash theme={null}
curl "https://www.intervyo.ai/api/v1/participants?accountSlug=<your-team-slug>"
```

Most server-to-server integrations should use an API key, not cookie auth.

## Rotating a key

API keys don't auto-expire. Rotate them on your org's secrets schedule (90 days is common):

<Steps>
  <Step title="Create the replacement key">
    Generate a new key alongside the old one — they can both be active.
  </Step>

  <Step title="Create the replacement">
    Generate a new key alongside the old one — both can be active at once.
  </Step>

  <Step title="Deploy the new key">
    Roll the new value through your secret manager. Every running service picks it up.
  </Step>

  <Step title="Deploy the new key">
    Roll the new value through your secret manager so every service picks it up.
  </Step>

  <Step title="Revoke the old key">
    Once you've confirmed traffic has moved over (the audit log on the old key will go quiet), revoke it. Revocation is instant — in-flight requests with the revoked key get `401`.
  </Step>

  <Step title="Revoke the old key">
    Once traffic has moved over (the old key's audit log goes quiet), revoke it. Revocation is instant — in-flight requests with the revoked key get `401`.
  </Step>
</Steps>

## Rate limits

Limits scale with your plan. Every response includes rate-limit headers:

```http theme={null}
X-RateLimit-Limit:      120
X-RateLimit-Remaining:  118
X-RateLimit-Reset:      1735689600
```

A `429 Too Many Requests` includes a `Retry-After` header (seconds). Back off and retry, or batch your work to lower request frequency.

## Authentication errors

<ResponseField name="401 Unauthorized">
  Missing, malformed, or revoked API key. Check the `x-api-key` header and verify the key under **Developer → API Keys**.
</ResponseField>

<ResponseField name="402 Payment Required">
  The workspace has no active paid plan (or is out of credits). The candidate-facing apply flow keeps working on trial; programmatic session creation requires a paid plan.
</ResponseField>

<ResponseField name="403 Forbidden">
  The key is valid but lacks the scope this endpoint requires. Add the missing scope, or use a different key.
</ResponseField>

<Note>
  Need OAuth, SSO-scoped tokens, or service accounts? Contact [hi@intervyo.ai](mailto:hi@intervyo.ai).
</Note>