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 engagements, plus company and contact engagement reads
engagements:writeReplace engagement contacts and tags
tags:readList and read tags
tags:writeCreate, update, and delete tags
transcript_timelines:readRead engagement transcript timelines
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

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