The API

Every screen in the console is served by the same API a script can call. The version sits in the path itself — /api/v1/… — under whatever address your installation is mounted at.

The route document lives inside the product

The complete list of routes, fields and values is Settings → API documentation, not this page. Three practical reasons:

• It is generated from the installation itself, so it always matches the version you are running rather than the version a website happens to describe.
• It carries the address a trial call will actually be sent to, and that address depends on the deployment.
• On a disconnected network there is no external documentation site to point at.

The screen also offers a Download openapi.json button, so the document can be handed to whoever writes the integration or fed to a code generator. Reaching it requires the docs.api permission, which is not granted by default: the full route map of your installation is organizational information, and an organization that wants its integrators to have it grants the permission deliberately.

Two ways to authenticate

Credential	How it travels	Who uses it
Session token	Authorization: Bearer	The browser. Issued at login, valid for the number of hours set in settings
Access token	X-API-Key, or the same Bearer header	Scripts and automated systems

Every route accepts one of the two — never both together.

Access tokens

Created in Settings → Access tokens, in two kinds:

Kind	Its permissions	What it suits
Personal	The intersection of the scopes chosen for it and its owner's live permissions, recomputed on every call	Work a person does in their own name. Narrow the person and every one of their tokens narrows with them
Service	The scopes chosen for it, capped by the creator's permissions at mint time and standing alone from then on	Nightly jobs and sync scripts, which have to keep working after whoever set them up has left

Scopes are keys from the permission catalog — one vocabulary, one editor, no second list to maintain.

What to know before issuing one

• The secret is shown exactly once, at creation and at rotation. There is no "show it again". A lost token is rotated, not recovered.
• A fixed prefix identifies the kind (cc_pat_ for personal, cc_svc_ for service), so a code repository or a scripts folder can be scanned for a credential someone left inside.
• Rotation mints a replacement with the same name, kind and scopes, and leaves the old one valid for a grace period you choose — because a credential cannot be swapped in two systems at the same instant. A grace of zero cuts the old one immediately, which is the "compromised, kill it now" case.
• Only the owner may rotate. Someone managing other people's tokens can revoke, not rotate — revoke says exactly what it does, whereas a rotation would quietly move the token to a new owner and leave the original integration dead.
• Expiry is chosen at creation, and "no expiry" is an explicit choice rather than a default someone falls into.
• A per-user quota, which an administrator can change. A token with no reason is a token nobody will revoke.
• Managing tokens is closed to tokens. Creating, re-scoping and revoking happen only from a signed-in session — otherwise a narrow token could clone itself wider.

Proving a token works

GET /tokens/me is the one route in token management that an access token may call itself. It answers who the caller is and what it may do, without touching business data — the first call worth putting in a new script.

Responses and errors

Responses are JSON. An error is returned in a detail field:

Code	Meaning
401	No valid credential — missing, wrong, expired or revoked
403	The credential is valid but lacks the permission for this action

The split is deliberate: one code for both meanings would send every permission problem off to re-check the token.

[VERIFY] — the compatibility policy between API versions, and what counts as a breaking change, is agreed with the product team before it is published here.