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

Scopes follow {resource}:{action} naming. The current public API 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
transcript_timelines:readRead transcript timelines for non-private engagements
users:readList and read users
workspace:adminFull access across the current public API surface for API keys; not supported for OAuth apps

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.
  • OAuth apps cannot request workspace:admin.
  • 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 permissions assigned to the key
  • Can be issued with workspace:admin when full public API access is needed
  • 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