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.
Step 1 — Open the Create Token modal
Click Create Token and fill in the form:
Token Name — describe what it's for (for example,
Nightly inventory sync). Required.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.
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.
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.
Click the token box (or the copy icon) to copy it.
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.
Tick I've copied my token to enable Done, then close the modal.
A token looks like this:
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:
Required headers
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.
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.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
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:
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.
Last updated
Was this helpful?