docs

Obtaining an API Token

AutoCISO API tokens are long-lived bearer credentials for service accounts — CI/CD pipelines, scripts, and AI clients connecting over MCP. This page covers creating, scoping, and revoking them.

Prerequisites

  • An AutoCISO account with the Owner or Manager role
  • Access to Settings → API Tokens

Tokens are issued per organisation. A token created in one org can never read another org’s data — the organisation is bound into the token itself and resolved on the server.

Creating a token

  1. Go to Settings → API Tokens
  2. Click New token
  3. Enter a name that identifies the integration (e.g., ci-pipeline-sbom-upload)
  4. Select the required scopes (see the table below)
  5. Optionally set an expiry date
  6. Click Create
  7. Copy the token immediately — it is only shown once

The token value looks like aci_<64 hex chars>_<64 hex chars> and always begins with aci_.

Scopes

These four scopes are the complete set. Any other value is rejected when the token is created.

ScopeGrantsUse it for
sbom:readRead SBOMs, components, findings, vendorsDashboards, reporting jobs
sbom:writeCreate/upload SBOMs, update findings, manage vendors — implies sbom:readCI/CD upload pipelines
mcp:readThe 22 read-only MCP toolsAI clients (Claude, Cursor, VS Code)
mcp:writeAdds the risk_create_draft MCP tool — implies mcp:readAI clients permitted to file risk drafts

Grant the narrowest scope that works. A CI job that only uploads SBOMs needs sbom:write and nothing else. See API Scopes for the endpoint-by-endpoint matrix.

Using the token

Include the token as a Bearer value in the Authorization header of every request:

Authorization: Bearer aci_your_token_here

Token lifecycle

  • Expiry is optional. Set expiresAt when creating a token and it stops working after that moment. Leave it unset and the token remains valid until revoked.
  • Revoke tokens from Settings → API Tokens when an integration is decommissioned. Revocation takes effect immediately.
  • If a token leaks, revoke it immediately and issue a replacement. Because each integration should hold its own token, revocation is surgical — only the leaked client loses access.
  • AutoCISO stores only a SHA-256 hash of the token. Nobody — including support — can recover the value after creation.

What tokens cannot do

  • Manage other tokens. GET/POST/DELETE on /api/v1/tokens reject API-token auth with 403. Token management requires an interactive user session.
  • Act as a user. Token requests carry no user identity, so endpoints that attribute actions to a person are unavailable to them.
  • Choose an organisation. There is no org_id parameter and no X-Org-ID header for API tokens.

Rate limits

There is no per-token application rate limit. A shared infrastructure limit of 20 requests per second per client IP applies at the edge and returns 429 Too Many Requests when exceeded.

The MCP endpoint is limited separately and more tightly — see MCP Errors and Retries.

Next steps

Last reviewed: 2026-09-09

Was this page helpful?

Esc