> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.askelephant.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.askelephant.ai/_mcp/server.

# 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 non-private engagements, plus company and contact engagement reads             |
| `engagements:private:read`  | Read private engagements in addition to non-private engagements; requires `engagements:read` |
| `engagements:write`         | Replace engagement contacts and tags for non-private engagements                             |
| `engagements:private:write` | Replace engagement contacts and tags for private engagements; requires `engagements:write`   |
| `tags:read`                 | List and read tags                                                                           |
| `tags:write`                | Create, update, and delete tags                                                              |
| `transcript_timelines:read` | Read transcript timelines for non-private engagements                                        |
| `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`

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

| 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 |