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

# Authentication

> Token format, scopes, and what a workspace token can reach.

Every request carries a bearer token:

```bash theme={null}
curl https://api.chatsailer.com/v1/me \
  -H "Authorization: Bearer sk_live_AbC123.xYz789"
```

There is no tenant or workspace header. The token identifies the workspace.

## Token format

```
sk_live_<selector>.<verifier>
        └──────┘ └────────┘
         lookup    secret
```

The `.` matters: both halves are base64url, whose alphabet includes `_`, so
splitting on anything else truncates some tokens. Send the string exactly as
issued.

Tokens from non-production environments are prefixed `sk_test_` instead.

Only the `selector` is stored. The `verifier` is hashed, so a lost token cannot
be recovered — ask a workspace administrator to create a replacement and revoke
the old one. Revocation takes effect immediately, not at the end of a cache
window.

## Scopes

A scope is `<resource>:<access>`. `read` covers list and retrieve; `write`
covers create, update, and delete.

| Resource      | Scopes                                      |
| ------------- | ------------------------------------------- |
| Contacts      | `contacts:read`, `contacts:write`           |
| Organizations | `organizations:read`, `organizations:write` |
| Deals         | `deals:read`, `deals:write`                 |
| Pipelines     | `pipelines:read`, `pipelines:write`         |
| Fields        | `fields:read`, `fields:write`               |
| Notes         | `notes:read`, `notes:write`                 |
| Activities    | `activities:read`, `activities:write`       |
| Tags          | `tags:read`, `tags:write`                   |
| Conversations | `conversations:read`, `messages:write`      |
| Campaigns     | `campaigns:read`, `campaigns:write`         |
| Analytics     | `analytics:read`                            |

Ask for the narrowest set that does your job. Calling an endpoint without its
scope returns `403 insufficient_scope`, and the message names the scopes you are
missing.

<Note>
  Scopes **intersect** with what your workspace is allowed to do — they never
  grant beyond it. A token with `deals:write` still cannot write deals in a
  workspace whose deals are mirrored from an external CRM. Call
  `GET /v1/capabilities` to see the effective policy per entity before you
  attempt a write.
</Note>

## Two limits worth knowing up front

**A token reads the whole workspace.** Sailer's per-user record visibility rules
apply to people, not tokens — a token has no user behind it. Anything in the
workspace is readable with the right scope, regardless of who owns the record.
Treat a token as workspace-wide access and scope it accordingly.

**Write policy still applies.** If a workspace mirrors an entity from an external
CRM, writes to that entity are rejected for everyone, tokens included. This is
deliberate: it stops the API from silently diverging from the system of record.
`GET /v1/capabilities` reports which entities you may write.

## Keeping tokens safe

* Server-side only. A token in browser or mobile code is a workspace-wide leak.
* Environment variables or a secret manager, never source control.
* One token per integration, so you can revoke one without breaking the others.
* Tell us immediately if one leaks and we will revoke it.