Start Here

Authentication and scopes

Send the correct Authorization header and request the scopes your integration needs
View as Markdown

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:

ScopePurpose
companies:readList and read companies
companies:writeCreate, update, delete, and manage company CRM associations
contacts:readList and read contacts
contacts:writeCreate, update, delete, and manage contact CRM associations
engagements:readList and read non-private engagements, plus company and contact engagement reads
engagements:private:readRead private engagements in addition to non-private engagements; requires engagements:read
engagements:writeReplace engagement contacts and tags for non-private engagements
engagements:private:writeReplace engagement contacts and tags for private engagements; requires engagements:write
tags:readList and read tags
tags:writeCreate, update, and delete tags via the public API (tags:write scope only). The in-product GraphQL API separately requires manager-or-owner workspace role for tag taxonomy mutations (createTag, updateTag, deleteTag, createTagFromSuggestion).
transcript_timelines:readRead transcript timelines for non-private engagements
users:readList and read users

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

  • expand=contacts requires contacts:read
  • expand=owner requires users:read

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

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

StatusMeaningCommon fix
401Missing, expired, or malformed credentialCheck the Authorization header format and credential validity
403Credential is valid but missing the route’s required or conditional scopeRequest or mint a credential with the scopes required by the route and any requested expansions