Authentication and scopes

Authentication modes in the live API

The live public API accepts two credential types in the Authorization header:

• OAuth bearer tokens: Authorization: Bearer <access-token>
• API keys: Authorization: sk-apik_<id>.<secret>

If you use an API key, do not add a scheme prefix. Send the raw key value.

Scope model

These scopes authorize Public API routes. They do not limit tools on the AskElephant MCP server, which acts with the connected user’s current AskElephant permissions.

Public API scopes follow {resource}:{action} naming. The current scopes are:

Some engagement reads also require additional scopes when you request expansions:

• expand=contacts requires contacts:read
• expand=owner requires users:read
• expand=transcript_timeline requires transcript_timelines:read and returns structured timelines (not plaintext expand=transcript)

Privacy-sensitive engagement reads also use an additive scope:

• engagements:read returns only non-private engagements
• engagements:private:read is required with engagements:read to read private engagement detail, include private engagements in list responses, or read transcript timelines and transcript comments for private engagements
• engagements:write updates non-private engagements only
• engagements:private:write is required to modify private engagements

Workspace engagement visibility

Workspace-scoped credentials use Public API scopes only. REST does not apply the credential creator’s in-app FGA or passport rules.

With engagements:read, a workspace API key or OAuth bearer token can list and read every non-private engagement in that workspace, even when the credential creator could not see those engagements in the AskElephant app.

Private engagements behave as follows:

• List responses omit private engagements unless the credential also has engagements:private:read with engagements:read.
• Direct engagement reads return HTTP 404 Not Found, not 403, when the engagement is private and the credential lacks engagements:private:read. This applies to GET /v2/engagements/{engagement_id}, GET …/transcript_timeline, and transcript comment reads.

Do not infer REST visibility from MCP access. MCP acts as the connected user; REST uses workspace scopes as documented here.

Bearer tokens

• Use bearer tokens when you need delegated user access.
• Tokens should be workspace-scoped and include the supported resource scopes required by the routes you call.
• Missing, expired, or malformed tokens return 401 with a WWW-Authenticate challenge.

API keys

API keys are best for server-to-server integrations:

• Format: sk-apik_<id>.<secret>
• Sent as the full Authorization header value
• Scoped to the workspace and Public API permissions assigned to the key
• Ideal for backend jobs, sync workers, and ingestion services

Common auth failures