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

# Create and manage API tokens

> Issue a token from the Sailer app, pick its scopes and expiry, and revoke it.

API tokens are created in the Sailer app by anyone with the **Configuration**
permission on the workspace. Organization admins have it by default. If you
don't, ask one of them to follow this page for you.

## Find the API tab

<Steps>
  <Step title="Open Company Profile">
    In the sidebar, under **Settings**, click **Company Profile**.

    <Frame>
      <img src="https://mintcdn.com/sailer-ai/hyvJTfOotG1Hhlzc/images/api-tokens/en/company-profile-nav.png?fit=max&auto=format&n=hyvJTfOotG1Hhlzc&q=85&s=76df65de9877f9608989e012891a33ec" alt="The Company Profile item under Settings in the Sailer sidebar" width="260" data-path="images/api-tokens/en/company-profile-nav.png" />
    </Frame>
  </Step>

  <Step title="Pick the workspace and open API">
    Click the company whose data the integration will use, then open the
    **API** tab.

    <Frame>
      <img src="https://mintcdn.com/sailer-ai/hyvJTfOotG1Hhlzc/images/api-tokens/en/api-tab.png?fit=max&auto=format&n=hyvJTfOotG1Hhlzc&q=85&s=70e38362877da7c13e13485c28254cca" alt="The API tab, listing two active tokens above the legacy API key" width="2560" height="1720" data-path="images/api-tokens/en/api-tab.png" />
    </Frame>
  </Step>
</Steps>

The tab lists every token for the workspace: its name, the last characters of
the token, how many scopes it has, its status, when it was created, when it was
last used, and when it expires. Click the scope count to see the full list.

## Create a token

<Steps>
  <Step title="Name it, set an expiry, pick scopes">
    Click **Create token**.

    * **Name**: what the token is for, such as the integration it belongs to.
      Up to 120 characters. Only people in the workspace see it.
    * **Expiration**: **Never expires**, **30 days**, **90 days**, or
      **1 year**. See [Expiry](#expiry).
    * **Scopes**: at least one. See [Choosing scopes](#choosing-scopes).

    <Frame>
      <img src="https://mintcdn.com/sailer-ai/hyvJTfOotG1Hhlzc/images/api-tokens/en/create-token.png?fit=max&auto=format&n=hyvJTfOotG1Hhlzc&q=85&s=5cb47c93080161f1cfbe5d99737e3cb3" alt="The Create API token dialog with a name, a 90-day expiry and three scopes selected" width="1536" height="2072" data-path="images/api-tokens/en/create-token.png" />
    </Frame>
  </Step>

  <Step title="Copy the token">
    Click **Create token**. The token is shown **once**. Click **Copy** and
    store it in your integration's secret manager or environment variables.

    <Frame>
      <img src="https://mintcdn.com/sailer-ai/hyvJTfOotG1Hhlzc/images/api-tokens/en/copy-token.png?fit=max&auto=format&n=hyvJTfOotG1Hhlzc&q=85&s=54b806d3ddad4952de0ebef0dbfb42af" alt="The one-time reveal of a new token, with a Copy button and a warning that it won't be shown again" width="1536" height="600" data-path="images/api-tokens/en/copy-token.png" />
    </Frame>

    Sailer keeps only a hash of the token, so nobody can show it to you again.
    This screen closes only when you click **Done**. If you lose the token,
    revoke it and create a new one.
  </Step>

  <Step title="Check it works">
    ```bash theme={null}
    curl https://api.chatsailer.com/v1/me \
      -H "Authorization: Bearer $SAILER_API_TOKEN"
    ```

    The response names the workspace and lists the token's scopes. See the
    [Quickstart](/guides/quickstart) for your first real request.
  </Step>
</Steps>

## Choosing scopes

The picker groups scopes by area, with one column per access level. **Read**
covers listing and retrieving records. **Write** covers creating, updating and
deleting them. **All read** selects every read scope, **Select all** selects
everything, and **Clear** removes every scope.

| Group | What it covers |
| - | - |
| **CRM** | Contacts, organizations, deals, pipelines, custom fields, notes, activities, tags, conversations, messages and campaigns |
| **Analytics** | Campaign and workspace metrics |
| **Agent Studio** | Agents, agent tools, knowledge base, queues, sandbox, simulations, evaluations and inference |

Pick the narrowest set the integration needs. A token reads the whole workspace
within its scopes, whoever owns the records. A call without the right scope
returns `403 insufficient_scope`, and the message names the missing scopes.

<Warning>
  Not every scope in the picker does something on an API token today:

  * **Agent Studio** scopes work only for OAuth apps. For Agent Studio, connect
    through [MCP](/mcp/auth) instead.
  * **Messages · Write** (`messages:write`) is not used by any endpoint. The
    public API can't send messages.

  [Authentication](/guides/authentication#scopes) lists which scopes have
  endpoints on `/v1`.
</Warning>

You can't change a token's scopes after creating it. To change them, create a
new token with the scopes you want, move the integration to it, then revoke
the old one.

## Expiry

| Option | The token stops working |
| - | - |
| **Never expires** | Only when you revoke it |
| **30 days**, **90 days**, **1 year** | That long after you create it |

Once a token expires, the API answers `401` and the token's status in the list
changes to **Expired**. You can't extend a token. Create a new one before the
old one expires, then revoke the old one.

Use an expiry for anything temporary: a trial, a one-off import, or a
contractor's access.

## Revoke a token

Revoke a token when an integration is retired, when the person who set it up
leaves, or whenever you think it might have leaked.

<Steps>
  <Step title="Click revoke">
    In the token's row, click the revoke icon at the end, then confirm.

    <Frame>
      <img src="https://mintcdn.com/sailer-ai/hyvJTfOotG1Hhlzc/images/api-tokens/en/revoke-token.png?fit=max&auto=format&n=hyvJTfOotG1Hhlzc&q=85&s=6d7575124052c0b58f34593b5e167bc0" alt="The Revoke API token confirmation" width="1024" height="376" data-path="images/api-tokens/en/revoke-token.png" />
    </Frame>
  </Step>

  <Step title="It stops working immediately">
    The next request with that token gets `401`. Revoking can't be undone.
  </Step>
</Steps>

Revoked tokens are hidden from the list. Turn on **Show revoked** to see them,
for example to check when something was turned off.

<Frame>
  <img src="https://mintcdn.com/sailer-ai/hyvJTfOotG1Hhlzc/images/api-tokens/en/revoked-tokens.png?fit=max&auto=format&n=hyvJTfOotG1Hhlzc&q=85&s=74e093a562d56994f55aa6d2c7457567" alt="The token list with Show revoked on: one revoked token and two active ones" width="2028" height="802" data-path="images/api-tokens/en/revoked-tokens.png" />
</Frame>

## Statuses

| Status | Meaning |
| - | - |
| **Active** | The token works |
| **Expired** | Its expiry date has passed. Requests get `401` |
| **Revoked** | Someone revoked it. Requests get `401` |
| **Legacy** | The workspace's older `X-API-KEY` credential. It can't be revoked here; see below |

**Last used** is updated at most every few minutes, so a token you just used
can still show an older time.

## The legacy API key

Below the token list, **Legacy API key** shows the workspace's single
`X-API-KEY`. Webhooks and older integrations use it; the `/v1` API does not.
Use API tokens for anything new.

**Regenerate** replaces that key right away. Everything that uses the old key
stops working until you update it, so find those integrations first.

## Good practice

* One token per integration, so revoking one never breaks the others.
* Keep tokens on the server. A token in browser or mobile code is a leak of the
  whole workspace.
* Keep tokens in environment variables or a secret manager, never in source
  control.
* If a token leaks, revoke it first and investigate afterwards.