***

title: Authentication and scopes
subtitle: >-
Send the correct Authorization header and request the scopes your integration
needs
slug: 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

Scopes follow `{resource}:{action}` naming. The current public API scopes are:

| Scope                       | Purpose                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| `companies:read`            | List and read companies                                                                      |
| `companies:write`           | Create, update, delete, and manage company CRM associations                                  |
| `contacts:read`             | List and read contacts                                                                       |
| `contacts:write`            | Create, update, delete, and manage contact CRM associations                                  |
| `engagements:read`          | List and read engagements, plus company and contact engagement reads                         |
| `engagements:write`         | Replace engagement contacts and tags                                                         |
| `tags:read`                 | List and read tags                                                                           |
| `tags:write`                | Create, update, and delete tags                                                              |
| `transcript_timelines:read` | Read engagement transcript timelines                                                         |
| `users:read`                | List and read users                                                                          |
| `workspace:admin`           | Full 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

| Status | Meaning                                                                   | Common fix                                                                                      |
| ------ | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `401`  | Missing, expired, or malformed credential                                 | Check the `Authorization` header format and credential validity                                 |
| `403`  | Credential is valid but missing the route's required or conditional scope | Request or mint a credential with the scopes required by the route and any requested expansions |