> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatbridge.algosmiths.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys, scopes, and the Bearer token header

## API keys

Every request to `/api/v1/` authenticates with a workspace API key in the `Authorization` header:

```
Authorization: Bearer cb_live_...
```

Keys are created and managed in **Settings → API Keys**. Each key is scoped to exactly one workspace —
a key issued for workspace A can never read or write workspace B's data, regardless of what other
workspaces its creator belongs to.

A complete authenticated request looks like this:

```bash theme={null}
curl https://api.algosmiths.com/api/v1/contacts/ \
  -H "Authorization: Bearer cb_live_..."
```

A missing, malformed, or revoked key returns `401 Unauthorized` with the standard
[error envelope](/errors). A valid key that lacks the [scope](#scopes) an endpoint requires returns
`403 Forbidden`.

<Note>
  If your workspace's trial has expired (and no paid plan is active), API keys become **read-only** —
  `GET` requests keep working, but writes (`POST`/`PATCH`/`DELETE`) return `403 Forbidden`. Reactivate
  the workspace from the dashboard to restore write access.
</Note>

## Scopes

A key only has the permissions explicitly granted to it. Request only what you need.

| Scope                                              | Grants                                                                     |
| -------------------------------------------------- | -------------------------------------------------------------------------- |
| `team.view`                                        | View team members                                                          |
| `chat.view`                                        | View conversations                                                         |
| `chat.send_message`                                | Send messages                                                              |
| `chat.assign`                                      | Update conversation status/priority/tags and reassign                      |
| `contact.view` / `contact.edit` / `contact.delete` | View / create+update / delete contacts                                     |
| `template.view`                                    | View message templates                                                     |
| `catalogue.view`                                   | View catalogue products                                                    |
| `inbox.view`                                       | View team inboxes                                                          |
| `ticket.view`                                      | View tickets, pipelines, stages, comments, activity                        |
| `ticket.manage`                                    | Create/update/delete tickets, comment, escalate, manage pipelines & stages |
| `flow.view`                                        | View WhatsApp Flows, submissions, metrics                                  |

<Info>
  `ticket.manage` deliberately covers both day-to-day ticket work *and* pipeline/stage configuration —
  there's no separate "admin" scope for tickets. The same reasoning applies to `chat.assign`, which
  covers both editing a conversation's status/priority/tags and reassigning it to a different
  teammate or inbox.
</Info>

## What's not yet in scope

WhatsApp Flows are **read-only** via the API today — creating, uploading, publishing, or deprecating a
Flow has to happen in the dashboard. Ticket SLA policies aren't exposed via the API at all yet. Both are
natural candidates for a future release.

The scopes table above is the complete list of scopes any `/api/v1/` endpoint actually checks. Workspace
membership manages a broader internal permission vocabulary (billing, team, WhatsApp account connection,
contact notes) — those permissions govern the dashboard only and aren't exposed as API key scopes today,
so granting them to a key has no effect on `/api/v1/` access.

## Escalation guard

A workspace member can never mint a key with more access than they hold themselves — if you don't have
`workspace.manage_billing` yourself, you can't create a key that has it either.