> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/authentication.md).

# Authentication & Tokens

Every Claret API request is authenticated with a **Bearer token**. Tokens are created from the Claret web app under **API Access** and passed in the `Authorization` header of each request.

{% hint style="info" %}
All API documentation uses a `{tenant}` segment in the URL path. Replace it with the name of the tenant making the call (for example, `demo`, `zymoeno`).
{% endhint %}

{% hint style="warning" %}
Looking for the old email-and-password `tokens/create` flow? That endpoint is deprecated. See [Migrating from Legacy Endpoints](/api-guide/migration.md) for the timeline and a side-by-side comparison.
{% endhint %}

## Creating a token

Tokens are managed in the Claret app under **Settings → Workspace Settings → API Access**, on the **Tokens** tab.

{% hint style="info" %}
The **API Access** page only appears if your workspace has the **Public API** module enabled. If you don't see it in the sidebar, contact a Workspace Admin.
{% endhint %}

![The Tokens tab on the API Access page](/files/x26bby6Z1ScyWbyIU1Tm)

### Step 1 — Open the Create Token modal

Click **Create Token** and fill in the form:

1. **Token Name** — describe what it's for (for example, `Nightly inventory sync`). Required.
2. **Permissions** — select the [scopes](/api-guide/scopes.md) the token needs. Checking **All Permissions** grants everything and disables the individual options; otherwise pick the specific scopes from the grouped list. At least one is required.
3. **Expiration** — choose **No expiration**, **30 days**, **90 days**, or **365 days**.

The **Create Token** button stays disabled until a name and at least one permission are set.

![The Create API Token modal](/files/MCL8SNkhDeWIpfdrZPrP)

{% hint style="info" %}
A token can never do more than the user who created it. Scopes are the first authorization gate; the creator's UI permissions are the second. See [Two-gate authorization](#two-gate-authorization).
{% endhint %}

### Step 2 — Copy the token

As soon as the token is created, a **Your New API Token** modal appears. This is the **only time** the full token is shown.

1. Click the token box (or the copy icon) to copy it.
2. The modal includes a **Quickstart** section with **cURL / Python / JavaScript** snippets, pre-filled with your tenant URL and token, so you can test it immediately.
3. Tick **I've copied my token** to enable **Done**, then close the modal.

![The token reveal modal with quickstart snippets](/files/GLk4YW5Tk3BbGOTFwUaA)

A token looks like this:

```
42|clrt_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789AbCd
```

The portion after the `|` always begins with `clrt_`. Treat the whole string as a secret; anyone holding it can act with the token's scopes and the creator's data access.

{% hint style="danger" %}
Claret stores only a hash of the token, never the plaintext. If you lose it you cannot recover it; revoke it and create a new one. Store tokens in a secret manager or environment variable, never in source control.
{% endhint %}

## Using a token

Pass the token as a Bearer credential on every request:

```bash
curl "https://plan.claret.app/{tenant}/api/v1/items" \
  -H "Authorization: Bearer 42|clrt_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789AbCd" \
  -H "Accept: application/json"
```

### Required headers

| Header          | Value              | Notes                                         |
| --------------- | ------------------ | --------------------------------------------- |
| `Authorization` | `Bearer {token}`   | Required on every request.                    |
| `Accept`        | `application/json` | Recommended. Ensures JSON responses.          |
| `Content-Type`  | `application/json` | Required on `POST` requests with a JSON body. |

{% hint style="info" %}
If a request is unauthenticated and the `Accept: application/json` header is missing, the server may return an HTML redirect to the login page instead of a JSON `401`. Always send `Accept: application/json` so authentication failures come back as structured errors.
{% endhint %}

## Two-gate authorization

Access is authorized at **two independent gates** on every request. A request must pass both.

1. **Token scope.** The coarse access category selected when the token was created (Read, Write, Compute, Workflow Sync, Workflow Replace). If the token lacks the scope an endpoint requires, the request returns `403`. See the [Scopes Reference](/api-guide/scopes.md).
2. **Creator's module permissions.** A token inherits the Claret UI permissions of the user who created it. If that user cannot see a resource in the app, neither can the token, and the request returns `403`.

{% hint style="info" %}
**Rule of thumb:** if the person who created the token can see the data in the Claret UI, the token can read it. If they can't, the token gets a `403`.
{% endhint %}

Because of the second gate, the data a token can reach changes if the creator's permissions change. Provision tokens from a user whose access matches the integration's needs.

## Token lifecycle

| Action             | Where                                              |
| ------------------ | -------------------------------------------------- |
| Create a token     | **API Access → Tokens → Create Token**             |
| List active tokens | **API Access → Tokens**                            |
| Revoke a token     | **API Access → Tokens →** revoke action on the row |

Revoking a token takes effect immediately. Any request made with a revoked token returns `401`.

## Quick connectivity test

Confirm a token works by calling a lightweight reference endpoint:

```bash
curl -s "https://plan.claret.app/{tenant}/api/v1/uoms" \
  -H "Authorization: Bearer {your-token}" \
  -H "Accept: application/json"
```

A `200` with a `data` payload confirms the token is valid and authorized. A `401` means the token is missing, malformed, or revoked; a `403` means it lacks the required scope or module permission.

## Related documentation

* [Quickstart](/api-guide/quickstart.md) — create a token and make your first call in five minutes.
* [Scopes Reference](/api-guide/scopes.md) — what each scope grants and which endpoints need it.
* [Error Reference](/api-guide/errors.md) — full list of status codes and how to resolve them.
* [Migrating from Legacy Endpoints](/api-guide/migration.md) — moving off the old token flow.