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

# Authentication

> Workspace API keys, scopes, and how to use them across the REST API, MCP server, and CLI.

Ontora supports two authentication methods:

| Method                | Header                        | Used by                             |
| --------------------- | ----------------------------- | ----------------------------------- |
| **Workspace API key** | `X-API-Key: ont_...`          | CLI, MCP, programmatic integrations |
| **Clerk JWT**         | `Authorization: Bearer <jwt>` | Web app, Ontora desktop client      |

For programmatic access, always use a workspace API key.

<Note>
  For interview campaign transcripts, responses, insights, and reports, create a **workspace API key** with the
  `interviews` and `exports` scopes. Vault retrieval keys are separate advanced keys that only work with
  `POST /v1/retrieval` and `POST /v1/retrieval/answer` for one selected context vault.
</Note>

## Creating a key

API keys are scoped to a single workspace. Only **workspace admins** can create or revoke them.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.ontora.com/v1/api-keys \
    -H "Authorization: Bearer $CLERK_JWT" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "CI integration",
      "workspace_id": "ws_...",
      "scopes": ["interviews", "exports", "webhooks"],
      "expires_in_days": 90
    }'
  ```

  ```json Response theme={null}
  {
    "id": "key_...",
    "key": "ont_live_abc123...",
    "key_prefix": "ont_live_abc1",
    "scopes": ["interviews", "exports", "webhooks"],
    "expires_at": "2026-07-23T00:00:00Z",
    "created_at": "2026-04-24T18:30:00Z"
  }
  ```
</CodeGroup>

<Warning>
  The full key is only returned **once**, on creation. Store it in a secret manager immediately. Subsequent `GET /v1/api-keys` calls return only the `key_prefix`.
</Warning>

You can also create keys from the dashboard: **Settings → API keys → Create**.

## Scopes

Scopes restrict what an API key can do. Pick the minimum set required.

| Scope        | Grants                                                                           |
| ------------ | -------------------------------------------------------------------------------- |
| `interviews` | Campaigns, contacts, lifecycle, transcripts, GraphRAG queries, synthesis reports |
| `exports`    | Markdown / ZIP transcript and report exports                                     |
| `webhooks`   | Manage webhook subscriptions and view delivery logs                              |
| `mcp`        | Connect to the MCP server                                                        |
| `*`          | All of the above (use sparingly)                                                 |

Endpoints declare the scope they require. A key without that scope receives `403 Forbidden`.

## Revoking a key

Revocation is immediate.

```bash theme={null}
curl -X DELETE https://api.ontora.com/v1/api-keys/key_... \
  -H "Authorization: Bearer $CLERK_JWT"
```

Listing keys never reveals the secret — only the prefix and metadata:

```bash theme={null}
curl https://api.ontora.com/v1/api-keys?workspace_id=ws_... \
  -H "Authorization: Bearer $CLERK_JWT"
```

## Rotating keys

Best practice: keep two keys live during a rotation, swap consumers over to the new key, then revoke the old.

1. Create a new key with the same scopes.
2. Update consumers (CI secrets, CLI config, MCP clients).
3. Revoke the old key once traffic has shifted.

## Errors

| Status                  | Meaning                                                     |
| ----------------------- | ----------------------------------------------------------- |
| `401 Unauthorized`      | Missing, malformed, or revoked key                          |
| `403 Forbidden`         | Key does not have the required scope, or workspace mismatch |
| `429 Too Many Requests` | Rate limit exceeded — see `Retry-After` header              |