Documentation
Credentials
How they are created, narrowed, rotated and revoked from the application.
Credentials are managed in the application, not through the API: creating one is a person's decision about their own access, and the public API cannot manufacture more access for itself. They live in Profile → API and integrations.
Two types
| Type | Who creates it | Expiration |
|---|---|---|
Personal (user) | Any user with the api_tokens.manage.own permission, from their profile. It acts with their access. | Required. 365 days max. |
Organization (admin) | An administrator with api_tokens.manage.company. It stays anchored to the administrator who created it. | Optional: its life is already tied to the owner keeping administrator capability. |
An `admin` credential self-revokes
If the owner loses administrator capability — role change, permission removed from the matrix, role deleted — the credential is revoked immediately, on the first request that uses it. It does not sit waiting for someone to review it.
Narrowing by resource
Beyond scopes, a credential can be limited to specific resources. There are four types and each has its own mode:
| Resource type | What it narrows |
|---|---|
workspace | Libraries and their files, and a turn's attachments. |
skill | Skills that are visible and attachable. |
area | Visible areas, and those assignable when creating rules or libraries. |
mcp_server | Connectors a turn can use. |
| Mode | Meaning |
|---|---|
unrestricted | Everything the user reaches at any given moment, not a snapshot from the day it was created. If they gain access to a new library tomorrow, the credential sees it. |
allowlist | Only the listed ids, and also intersected with the user's live access. An empty list grants nothing. |
Note
A credential in allowlist mode over a type cannot create new resources of that type: trying returns 403 api_v1_resource_policy_create_denied. Narrowing to a list while allowing new items to be added to it would be contradictory.
Access token lifetime
Each credential defines how long the token it issues lasts: between 60 seconds and 24 hours, defaulting to 1 hour. A token never outlives its credential: if the credential has ten minutes left, the token is issued with ten minutes.
Rotating the secret
Rotating generates a new client_secret and kills that credential's live tokens on the next request, without waiting for them to expire. The client_id does not change.
You cannot deploy the new secret before rotating
The new secret is generated by the rotation: it does not exist beforehand, and there are never two valid secrets at once. Rotating has, by definition, a 401 window from the rotation until you finish deploying the secret it returned. It is the emergency path: if the secret leaked, that window is the right price.
To rotate with no downtime, do not rotate: use a parallel credential.
- Create a new credential with the same scopes and the same resource restrictions.
- Deploy its
client_idandclient_secret. Both credentials work at the same time. - Check
last_used_atto confirm traffic moved to the new one. - Revoke the old one.
Note
A running turn is not cut mid-flight by a rotation: what stops being valid is the access token, so the next request is the one that fails. Retrying after fetching a new token with the new secret works.
- Rotate if the secret leaked, if someone who knew it left, or on a schedule.
- A revoked credential cannot be rotated: create a new one instead.
- If two people rotate at once, the second gets a conflict instead of leaving someone holding a secret that no longer authenticates.
Revoking
There are two different things you can revoke, and it is worth not confusing them:
| What | Where | Effect |
|---|---|---|
| An access token | `POST /api/oauth/revoke` | That token stops working. The credential stays alive and can issue more. |
| The credential | The application | All its tokens are cut and it cannot issue new ones. It is irreversible. |
What gets recorded
Every API request leaves an audit row — including rejected ones, because a repeated 401 from a misconfigured client is exactly what you want to be able to see. It is kept for 90 days.
request_id, method, route template, status, duration, IP and user agent.- Credential, company, user and the scopes the operation required.
- For a turn: chat, message, permission mode and tokens consumed.
What is NOT stored
Not the Authorization header, not the OAuth form, not the Idempotency-Key in the clear — only its hash. You can use one of your own business ids as the key without that value landing in our tables.
The credential also records last_used_at, which is how you spot an integration that went dark — or one that is still alive and nobody remembers.