Authentication

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.

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.

Creating a key

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

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
  }'

{
  "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"
}

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.

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.

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:

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.

Create a new key with the same scopes.
Update consumers (CI secrets, CLI config, MCP clients).
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

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

Authentication

Creating a key

Scopes

Revoking a key

Rotating keys

Errors

​Creating a key

​Scopes

​Revoking a key

​Rotating keys

​Errors

Creating a key

Scopes

Revoking a key

Rotating keys

Errors