API tokens

Every non-browser client — the CLI, the GitHub Action, the MCP server — authenticates with a bearer token.

The izri_ prefix is load-bearing

All tokens start with izri_. This is not cosmetic. The API short-circuits to bearer-token validation only when it sees that prefix; anything else falls through to cookie-session handling and produces an opaque 401 with no explanation.

If you get an unexplained 401 with a token you believe is valid, check the prefix before anything else. A truncated copy-paste that lost the prefix looks exactly like an expired token.

Minting a token

From organization settings, create a token and select its scopes. Copy it immediately — it is shown once and stored hashed.

A token can hold a subset of your role's scopes, never more. See organizations and roles for the full role-to-scope matrix.

Scoping

Grant the minimum the client needs.

Client	Typical scopes
GitHub Action	analysis:run, tests:run, projects:read
CLI (local dev)	analysis:run, tests:run, projects:read
MCP server	projects:read, tests:read, analysis:read — add tests:run to let the agent trigger runs
Read-only dashboards	projects:read, tests:read, analysis:read

A CI token does not need tokens:write or org:write. If a leaked CI token can mint more tokens, the blast radius of a leak is unbounded.

Using a token

export IZRI_API_TOKEN=izri_xxxxxxxxxxxx
export IZRI_API_URL=https://api.izri.ai

- uses: legendify-dev/izri/apps/github-action@v1
  with:
    api-token: ${{ secrets.IZRI_API_TOKEN }}

Directly against the API:

curl -H "Authorization: Bearer izri_xxxxxxxxxxxx" \
     https://api.izri.ai/health

Rotation

1. Mint the new token.
2. Update every consumer — CI secrets, local environments, MCP configs.
3. Revoke the old one.

In that order. Revoking first means a window where CI fails on every PR.

Tokens do not expire on their own. Rotate on a schedule you choose, and immediately whenever someone with token-minting rights leaves.

Tokens outlive role changes

A token's scopes are fixed when it's created. Demoting someone from ADMIN to MEMBER does not shrink the tokens they already minted. Revoke and reissue as part of any role change that's meant to remove access.

Never commit a token

Use repository secrets in CI and your environment locally. A token in git history is compromised even after the commit is removed — rotate it rather than rewriting history.

Related

• Organizations and roles — what scopes you can grant.
• CLI — where the token goes.