API Tokens

Creating and storing a token

Creating a token provisions a hidden service account with the admin role in the current company; the token value is shown exactly once, in the create response. Deleting a token also removes the underlying service account.

Only a company administrator — a human signed in through the cabinet session, or platform staff — may create or rename a token; a manager or agent gets a plain 403. Calling POST/PATCH as the API token itself is never allowed, whatever permissions the role carries, including from the very service account the token represents — such a call is always refused with 403 and error: "api_token_admin_only". Listing tokens, fetching one by id, and deleting are not bound by this rule — they can be called with the API token itself, as long as it carries api_token.view / api_token.delete.

Deleting a token is how you switch off an integration that acts on behalf of the company, including the integration of a partner that set up your company: every call with the deleted token immediately gets 401. Deleting the token also revokes any temporary embed tokens (POST /v1/embed/auth, they live 8 hours) it minted — otherwise the integration could keep working through those for a while after the deletion. A service account cannot be demoted or revoked through member management (/v1/companies/current/members/{memberId}/role, .../revoke) — such calls answer 404. A deleted token cannot be restored: to bring the integration back, create a new token and hand it to the integrator. Issuing, renaming, and deleting a token are all recorded in the platform audit log.

Reading a token

When a token is read (listed or fetched by id) the token field is no longer returned — only metadata is available (name, description, created_at, last_used_at).

Which token may call this group

Since 2026-09-28 every endpoint of this group requires a full token — a user session or an API token with all abilities. A narrow token with a restricted ability set (for example the token of an embedded CRM window) gets 403 with error: "full_token_required": this way a short-lived token cannot mint itself a permanent one.

Request body

The create and update request body accepts:

• name — required, a string up to 255 characters.
• description — optional, a string up to 1000 characters, nullable.