Access Model & Scopes

AutoCISO API tokens are deny-by-default. A token is not a general-purpose key to your workspace: it opens four specific surfaces, each guarded by its own scopes, and only for the features your organisation’s plan includes. This page is the single reference for all three gates.

Three gates on every call

Every request made with an API token passes three checks:

1. Allowlist. Is the path one of the four surfaces below? If not: 403 FORBIDDEN, whatever the token carries.
2. Scope. Does the token carry the scope the route needs? If not: 403 INSUFFICIENT_SCOPE, naming the scope.
3. Plan. Does your organisation’s plan include the feature? If not: 402 FEATURE_GATED, naming the lowest plan that does. Over MCP, tools for features outside your plan are simply not listed.

The allowlist is always checked first. The scope and plan checks run in a surface-specific order: on the supply-chain and questionnaire routes the plan is checked before the scope, on the lifecycle routes the scope comes first. A request that fails both therefore gets 402 on the former and 403 on the latter.

A few actions inside an allowlisted surface additionally refuse every token with 403 HUMAN_APPROVAL_REQUIRED — see Human-only actions. No scope, plan or role widens any of these gates.

The four surfaces

Every other path returns 403 FORBIDDEN when called with an API token:

{
  "data": null,
  "error": {
    "code": "FORBIDDEN",
    "message": "API tokens are not permitted on this endpoint"
  }
}

The check runs during authentication, before routing and before scopes are evaluated.

What stays closed, and why

Interactive endpoints — employees, access reviews, ISO projects, evidence, billing, settings — answer only to a signed-in user, so that every change carries a real person’s identity in the audit trail. In particular:

• The lifecycle and employee endpoints (/api/v1/lifecycle/* and /api/v1/employees/*) stay closed to tokens. Off-boarding and on-boarding data reaches a token only through the purpose-built /api/v1/jml/ endpoints, which never return the raw employee record.
• Tokens cannot manage tokens. GET, POST and DELETE on /api/v1/tokens (endpoint reference) reject API-token authentication, so a leaked token cannot mint replacements for itself.
• /api/v1/payloadlog/* explicitly denies API tokens.

For programmatic read access to risk, ISO, access intelligence, supplier, compliance, monitoring, privacy or audit data, use MCP — not REST.

The eight scopes

These eight are the original scopes: they reach the supply-chain, MCP, supplier-questionnaire and lifecycle surfaces described below. Nine newer read scopes are covered in Read scopes for platform data.

Implication is one-directional: a token with sbom:write can read, but a token with sbom:read cannot write. The families are independent:

• sbom:write grants nothing over MCP, and mcp:write grants nothing over REST.
• mcp:write grants neither supplier_template:read nor supplier_template:write. The questionnaire tools return scoring fields no other tool exposes, so they sit behind their own scope pair.
• mcp:write does not imply pii:read, and pii:read implies nothing. On its own pii:read grants nothing over REST and unlocks exactly two MCP tools; a token with only pii:read sees two tools in tools/list. Combined with jml:read it adds names and emails to the case endpoints — see Employee identity.
• jml:read implies nothing and grants nothing over MCP. A token holding jml:read together with pii:read must expire within 90 days.

Scopes are fixed when a token is created. To change them, create a new token and revoke the old one — see Rotating a token.

Read scopes for platform data

Nine more scopes give a token read-only access to platform data over REST. They are live: a token that holds one can call the operations listed below, and nothing else. The create-token dialog marks a scope Not live for your organisation yet only if its endpoints are switched off for your organisation, and you can still select it.

Employee names and emails are not part of employee:read. They are returned only to a token that also holds pii:read, which is a separate Owner-granted scope with its own limits (see above). Every read that discloses identities, and every read of the audit trail, is recorded in your organisation’s Audit Trail.

Rules that apply to every scope in this table:

• Always read-only. None of them implies another scope, and none can write.
• An expiry is required. Pick a date no later than the longest expiry in the table. If the token also holds another scope with a shorter ceiling, the lowest ceiling wins: jml:read is 365 days, and any token that holds pii:read is 90 days. See Expiry rules.
• Granting is checked when the token is created. Owner-only scopes are refused for a Manager with 403 OWNER_REQUIRED; a scope your role may not grant gets 403 INSUFFICIENT_ROLE.
• The creator must stay qualified. If the person who created a token later loses the role the token’s scopes need, or leaves the organisation, AutoCISO suspends the token. A suspended token is refused like a revoked one and is not resumed; the token list shows suspendedAt and suspendedReason. Create a replacement.
• A plan can still say no. A scope never unlocks a feature your plan lacks; the call returns 402 FEATURE_GATED naming the lowest plan that includes it.
• At most 40 scopes per token, as explicit names. A wildcard such as asset:*, or a preset name, is refused with 400 SCOPE_INVALID.

Audit trail integrity: audit_log:verify

One more read-only scope lets a token run the Audit Trail integrity check (Verify the audit trail hash chain) and nothing else: it does not read audit entries, implies no other scope and is implied by none. Reading the entries needs audit_log:read, above.

The expiry rules and the other rules above apply. What the result shows a token, and how fresh it is, is described in Audit Trail Integrity.

Presets

The create-token dialog offers two presets that only tick boxes for you; the token stores the individual scope names, never the preset. Neither preset includes pii:read or any of the original eight scopes. BI read-only does not include audit_log:verify.

To see exactly which scopes your role may grant, and whether their endpoints are live, open API Tokens and click Create Token; the dialog reads the same list from GET /api/v1/tokens/scopes (reference).

Suspended organisations

While an organisation is suspended, a token of that organisation is refused with 403 ORG_SUSPENDED on every surface a token can reach: supply chain, supplier templates, lifecycle, the MCP endpoint and the read endpoints for the scopes above once they are published. The token itself is unchanged: calls work again as soon as the organisation is reactivated. The refusal carries no plan or organisation details. The suspension can take up to 30 seconds to take effect.

REST scope matrix

All paths are relative to https://api.autociso.io/api/v1.

Supply chain — sbom:*

Requires the Supply Chain Security feature (The Growth plan or higher). Reference: Supply chain API; per-endpoint pages for SBOMs, findings and vendors.

Supplier questionnaires — supplier_template:*

Requires the Supply Chain Security feature (The Growth plan or higher). Reference: Supplier questionnaires API.

Employee lifecycle — jml:read

Read-only. Requires the Employee lifecycle feature (The Seed plan or higher). Limited to 5 requests per second per token, burst of 30 — see Errors & rate limits. References: Off-boarding API, On-boarding API.

The lifecycle API is switched on per deployment; where it is not enabled, these paths answer 403 FORBIDDEN.

MCP scope matrix

Over /mcp, scope decides which tools appear in tools/list. A tool the token may not use is filtered out of the listing rather than failing at call time. The server registers 66 tools in total (61 read-only, 5 write); which of them a token sees depends on its scopes and on the organisation’s plan — a scope never unlocks a feature the plan does not include (see Scope is not entitlement). Counts below are for an organisation on The Scale:

A token needs mcp:write and supplier_template:write together to see all 5 write tools, and pii:read on top to see all 66. Every write tool has a second gate: it is hidden unless MCP writes are enabled for the deployment. A token holding every write scope against a deployment with writes disabled sees only the 61 read tools (59 without pii:read). employee_resolve and employee_lookup are likewise registered only where employee identity access is enabled.

Human-only actions

Inside the questionnaire-authoring surface, a supplier_template:write token can open a draft, edit it and call submit, moving it to Awaiting approval. It cannot go further: publish, reject (the “send back” action in the console), archive, unarchive, default and DELETE /{templateId} refuse every API token with 403 HUMAN_APPROVAL_REQUIRED, whatever scope it holds. Publishing changes how every new supplier assessment is scored, with no recall, so it always needs a person — there is no supplier_template:publish scope.

Edits made through a token count as edits by the person who created the token, so a token cannot be used to get around the second approver. See Supplier questionnaires.

Access revocation follows the same rule. Marking an audit upload as a complete snapshot of an asset (is_complete_snapshot=true on the console upload) is accepted from a signed-in person only: an API token that sends it gets 403 HUMAN_APPROVAL_REQUIRED. A complete snapshot never revokes anything by itself. Once it has no pending review tasks and is large enough (at least 3 rows and at least 20% of the asset’s current active grants), active grants that it does not list become possible revocations, and an Owner or Manager approves or keeps each one in the console, on the Access page. This review is available to signed-in people only, never to API tokens.

When a gate refuses

{
  "data": null,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "this API token does not have the required scope: sbom:write"
  }
}

The full list of status codes and rate limits is in Errors & rate limits.