Authentication, keys and scopes
Every endpoint (except the public GET /api/v1 discovery document, the OpenAPI spec and the Swagger UI) requires an API key in the Authorization header:
Authorization: Bearer sk-live-...
Key types
Type | Behaves as |
|---|---|
Personal | Acts as the issuing user; data is RLS-scoped to what that user can see. |
Organization | Service-principal key scoped to the organization. |
Some endpoints require a specific tier: explicit-agent answers, ingest and capture require a personal key; the help-desk and automation endpoints require an organization key. The endpoints reference lists the requirement per endpoint.
Create keys in Settings -> API keys. Some endpoints require a personal key (see key_type).
Scopes
A key carries one or more scopes; grant the narrowest set it needs. A key only ever sees data its owner can already access.
Scope | Grants |
|---|---|
| Search and read knowledge; download published Creations. |
| Generate synthesized answers; organization-grounded claims include citations. Grounding behavior follows the selected answer mode. |
| Save notes, documents, or captured web pages as review-queue drafts. |
| Read help-desk conversations, post operator replies, resolve them (organization keys only). |
| Subscribe to and poll the organization's event stream for Zapier/n8n/Make (organization keys only). |
| Reserved for future administrative operations. |
OAuth 2.1 (MCP only)
MCP connections can authenticate with OAuth 2.1 instead of a static key — Authorization Code + PKCE (S256) with Dynamic Client Registration, advertised at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. Claude and ChatGPT do this automatically when you add the server. The REST endpoints use API keys only.