API Tokens

An API token is a long-lived bearer credential for a machine: a CI/CD pipeline, a nightly script or an AI client connected over MCP. Tokens belong to an organisation, carry one or more scopes, and reach only the endpoints listed in the Access model — every other endpoint answers 403 FORBIDDEN.

Before you start

• You need the Owner or Manager role. Only an Owner can grant pii:read, audit_log:read, audit_log:verify, access_review:read and employee:read; every other scope needs an Owner or Manager of the organisation itself. Other roles can view the token list but not create or revoke tokens. Tokens cannot be created or revoked from a support session.
• Decide which scopes the integration needs. The full list and what each grants is in The eight scopes and Read scopes for platform data.
• Tokens are issued per organisation, and the organisation is bound into the token on the server. A token created in one organisation can never read another’s data.

Create a token

1. Open the user menu (your name at the bottom of the sidebar) and choose API Tokens (screen reference).
2. Click Create Token.
3. Enter a name that identifies the integration, for example ci-pipeline-sbom-upload.
4. Select the scopes, or pick a preset (Read everything or BI read-only) and adjust. Use the search box to find a scope by name or id, tick a group’s checkbox to select all its scopes, and read the selected count above the list. Scopes are grouped as Supply chain, Supplier templates, MCP, Employee lifecycle, Assets and access, Risk, Suppliers, ISO and compliance, People, Audit trail and Sensitive. A scope you may not grant is disabled with Only an organisation Owner can grant this scope. A token can hold at most 40 scopes.
5. Choose Expires: Never, 30 days, 90 days, 180 days, 1 year or Custom date. Some scopes require an expiry and cap how far out it can be — see Expiry rules.
6. Click Create Token. If you selected Employee identity (pii:read), confirm Grant employee identity access?.
7. Copy the value from the Token Created dialog and click I have copied the token. It is shown only once.

A token looks like aci_<64 hex chars>_<64 hex chars> and always begins with aci_. AutoCISO stores only a SHA-256 hash of it; nobody, including support, can recover the value later.

Use the token

Send it as a bearer token in the Authorization header of every request:

Authorization: Bearer aci_your_token_here

REST endpoints live under https://api.autociso.io/api/v1; MCP is https://api.autociso.io/mcp. Start with the REST quickstart or the MCP quickstart.

Expiry rules

The lowest ceiling wins: a token holding audit_log:read and pii:read must expire within 90 days.

Scope for audit trail integrity

It reads the integrity of the audit chain only, not the entries. It implies no other scope and no other scope implies it.

When a scope needs an expiry, the console disables Never, disables the options that are longer than the ceiling, and preselects 90 days. A missing or too-long expiry is rejected with 422 EXPIRY_REQUIRED or 422 EXPIRY_TOO_LONG. Where your plan does not include Employee lifecycle, the dialog warns that jml:read calls will return 402 until you upgrade.

Handle tokens safely

• Header only. Send the token only in the Authorization: Bearer header — never in a query string, a URL, a log line, a chat message or a ticket.
• Server-side only. Tokens are server-side credentials. Do not embed one in a browser page, a mobile app or a client-side script.
• One token per integration. A leaked token then costs you one integration, not all of them, and revocation is surgical.
• One token per client tenant. If you are an MSP or consultant serving several client organisations, each client creates its own token and you store one token per client, in separate secrets. There is no cross-tenant token.
• Store it in a secrets manager (GitHub Actions secrets, a cloud KMS, Vault). Never commit it to source control.
• Prefer 90 days, and rotate on that schedule — immediately when the person who set up the integration leaves.
• Personal data has a retention. Names and emails returned to a pii:read token, and the pseudonymised data from jml:read, are personal data. Keep only what the integration needs, under your own retention rules, and delete it when you no longer need it.

Rotating a token

Rotation is create-then-revoke, in that order, so the integration never loses access:

1. Create the replacement with the same scopes (for pii:read, as an Owner, with a fresh expiry of at most 90 days).
2. Install the new value in the integration’s secret store and confirm a call succeeds.
3. Revoke the old token.

The token list shows Expires in N days in the status column once a token is within 14 days of expiry. A pii:read token needs rotating every quarter at the latest.

Revoke a token

On API Tokens, click Revoke on the token’s row and confirm. Revocation takes effect immediately. Revoke a token when its integration is decommissioned, and at once if it may have leaked — then create a replacement.

Why a token was refused

Creating a token can fail with a stable code. Match on the code, not the message.

Once a token is in use, a token whose organisation is suspended is refused with 403 ORG_SUSPENDED on every token-accessible surface (supply chain, supplier templates, lifecycle, the MCP endpoint and the newer read endpoints once published), and a token whose creator lost the required role is suspended (the list shows suspendedAt and suspendedReason) and then refused like a revoked one. Full list: Errors & rate limits.

Token creation and revocation are recorded in the audit trail (api_token.created, api_token.revoked).

Token management endpoints

These four endpoints are the one part of the public surface that an API token cannot reach. They require an interactive user session (a JWT sent as Authorization: Bearer <jwt>) held by an Owner or Manager; an aci_ token receives 403 FORBIDDEN. The base URL is https://api.autociso.io/api/v1.

Creation and revocation are written to the audit trail as api_token.created and api_token.revoked. Everything else in the API reference is called with the token you create here.

What tokens cannot do

• Manage tokens. /api/v1/tokens refuses API-token authentication; token management needs a signed-in user (see Token management endpoints).
• Choose an organisation. There is no org_id parameter and no X-Org-ID header for tokens.
• Change their scopes. Scopes are fixed at creation; rotate to a new token instead.
• Approve or publish. Human-only actions refuse every token — see Human-only actions.

Each token’s list entry also shows lastUsedAt and, once the token has been used, a daily activity summary (requests, rows returned, distinct routes, last route).

Rate limits per token and per IP are listed in Errors & rate limits.