API Keys

API keys authenticate every request to the Asiri REST API. They are minted per-workspace, carry an explicit set of scopes, and are passed via the Authorization: Bearer header.

Minting a key

In the dashboard:

Go to Settings → API Keys.
Click New Key.
Give it a human-readable name (e.g. prod-api-server).
Pick the scopes — start with the minimum your integration needs.
Copy the secret. We show it exactly once.

The dashboard records the key’s id, name, scopes, last-used timestamp, and the user who minted it. The secret itself is hashed at rest; we cannot recover it for you.

Scopes

Scopes are external API permissions. A key can call a route only when the route is on the public allowlist, the creating user’s role can use the underlying product area, and the key carries one of the route’s required scopes. Use the smallest scope set that matches the integration.

Common scopes:

Scope	Grants
`reports:read`	Compliance dashboards, report runs, and summaries.
`reports:write`	Queue report builds and compliance dossier exports.
`audit:read`	Tenant audit events and webhook delivery logs.
`webhooks:read`	Webhook subscription reads.
`webhooks:write`	Webhook create, update, delete, and test actions.
`files:read`	File metadata and clean download URLs.
`files:write`	File presign, completion, and delete workflows.
`controls:read`	Control status, mappings, and test-health reads.
`controls:write`	Control test-result writes.
`evidence:read`	Evidence item and source reads.
`evidence:write`	Evidence source and evidence item creation.

A request to an endpoint that requires a scope the key does not carry returns 403 Forbidden with an rbac_denied or forbidden error envelope.

The generated API Reference lists the exact required scope on every operation. Bare capability scopes like reports, tenant settings scopes, and wildcard * are not accepted for newly minted public API keys.

Bearer header

Every request must include the secret as a bearer token:


GET /v1/reports/overview HTTP/1.1
Host: api.asiri.ng
Authorization: Bearer asiri_live_<your-token>

Token prefixes reflect the environment that minted them:

Environment	Prefix
Production	`asiri_live_`
Staging	`asiri_stg_`
Development	`asiri_dev_`
Test	`asiri_test_`

See Authentication.

Local demo key

For local/demo work, use the committed API script after the demo tenants exist:


pnpm --filter @asiri/api create-demo-api-key -- --tenant lagos-pay --name docs-demo

The script defaults to reports:read,audit:read,webhooks:write. Pass --scopes with a comma-separated list when a demo integration needs a different public scope set. The script prints the full token once and stores only the hash and prefix. Re-running it creates a new key; existing tokens cannot be recovered.

Rotating

To rotate a key without downtime:

Mint a replacement key with the same scopes.
Roll the new value into your secret manager / Kubernetes secret / Worker binding.
Redeploy.
After confirming traffic flows on the new key (use the last-used column), revoke the old key.

Revoking

A revoked key fails immediately with 401 unauthorized. Revocation is recorded in the audit log with the actor and timestamp. Revoke any key you suspect has leaked — there is no “pause” or “disable” mode.

Key hygiene checklist

Use a separate key per service (don’t share between API server, worker, and CI).
Store secrets in a vault, not in source.
Rotate at least every 90 days.
Monitor the audit log for anomalous IPs / user agents.
Revoke immediately on offboarding or suspected leak.