Authentication & Tokens

How to create and use Claret API tokens, and how access is authorized.

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.

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

Looking for the old email-and-password tokens/create flow? That endpoint is deprecated. See Migrating from Legacy Endpoints for the timeline and a side-by-side comparison.

Creating a token

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

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.

The Tokens tab on the API Access page

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

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.

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

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.

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.

Using a token

Pass the token as a Bearer credential on every request:

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.

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.

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.

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.

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.

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:

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 — create a token and make your first call in five minutes.

• Scopes Reference — what each scope grants and which endpoints need it.

• Error Reference — full list of status codes and how to resolve them.

• Migrating from Legacy Endpoints — moving off the old token flow.