Skip to main content

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.

Ontora supports two authentication methods:
MethodHeaderUsed by
Workspace API keyX-API-Key: ont_...CLI, MCP, programmatic integrations
Clerk JWTAuthorization: Bearer <jwt>Web app, Ontora desktop client
For programmatic access, always use a workspace API key.

​
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
  }'
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.
ScopeGrants
interviewsCampaigns, contacts, lifecycle, transcripts, GraphRAG queries, synthesis reports
exportsMarkdown / ZIP transcript and report exports
webhooksManage webhook subscriptions and view delivery logs
mcpConnect 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.
  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

StatusMeaning
401 UnauthorizedMissing, malformed, or revoked key
403 ForbiddenKey does not have the required scope, or workspace mismatch
429 Too Many RequestsRate limit exceeded — see Retry-After header