API Tokens

API tokens give external systems and scripts programmatic access to your concorbit workspace using your user account's permissions. Each token is a bearer credential with a configurable expiry (7 days, 30 days, 90 days, or 1 year) and can be revoked at any time.

URL: /settings/api-tokens
Required permission: api.tokens

How to get there

1. Go to Settings from the sidebar.

2. Open the API tokens card.

Creating a token

1. Click Create token in the top-right.

2. Enter a recognisable Token name (e.g. CI/CD Pipeline, Zapier integration, Backup script). This is the only label you will see later, so make it specific enough that you can tell which token is which when you have a few.

3. Select at least one ability from the list. Each ability unlocks a specific group of endpoints (e.g. contacts:read for read-only contact access, tickets:write for ticket creation). Choose the narrowest set your integration needs. Wildcard (*) tokens are no longer issued, and any presented at /api/* are rejected.

4. Click Generate token.

5. The plaintext token is shown in a green-bordered card immediately after creation. Copy it now: this is the only time the full token will ever be displayed. After you dismiss the card, only a hash is stored server-side.

Tokens are bound to the user account that created them AND the tenant you were logged in to. Re-mint if you move between tenants. Old tokens whose pinned tenant no longer matches your current tenant return 401.

See the authentication guide for the full list of abilities + the endpoints each one unlocks.

Using a token

Pass the token as a bearer credential in the Authorization header:

Authorization: Bearer <your-token-value>

API endpoints live under /api/* and require a bearer token (session cookie auth is rejected here). Tokens only get access to the abilities you chose at creation: the bearer middleware checks every endpoint's required ability against the token's grants and returns 403 if it doesn't match.

The token list

The page lists every token you have created. Each row shows:

Only your own tokens appear here; each user manages their own tokens independently.

Revoking a token

Click Revoke on the row. The token stops working immediately. Any service still using that token will start receiving 401 Unauthorized responses.

Revoke a token whenever:

• The integration that used it has been decommissioned.

• The token may have leaked (pushed to a public repo, pasted into a chat, etc).

• A team member leaves and their tokens should be cut off.

Notes and gotchas

• You cannot recover a lost token. The plaintext value is only shown once at creation. If you lose it, revoke the old token and create a new one.

• Tokens carry the abilities you picked at creation, intersected with the user's permissions. A token made by an admin with vault:read granted can reveal credentials; the same ability granted on a user without the vault.reveal permission would still fail at the controller-level policy check.

• Tokens expire. You pick the lifetime at creation (7 days, 30 days, 90 days, or 1 year; 90 days is the default). Set a calendar reminder for long-running integrations so they don't silently break when the token lapses.

• Deactivating a user invalidates their tokens. If you remove a user from the workspace, their tokens stop working too.

• Moving a user between tenants invalidates their existing tokens. Tokens are tenant-bound at mint: a token pinned to tenant A returns 401 once the owning user is moved to tenant B. Re-mint from the new tenant.

• Wildcard tokens are rejected. If you have a legacy token from before March 2026 carrying the * ability, it will now return 403. Re-mint with explicit abilities.