Authentication

Bearer keys

Authorization: Bearer <token>

Anything else — a missing header, a malformed one, an unknown, revoked or expired key — is:

{ "error": "unauthorized" }

with 401.

Issuing a key

Settings → API keys, needing api_key.manage.

The raw token is shown once, at creation. Verity stores only a SHA-256 digest and cannot show it again. If it is lost, revoke the key and issue another.

Every issue and revoke is written to the audit trail.

Scopes

Scope	Grants
account_read (default)	entity.view, entity.review.view, provider_fetch_run.view
account_full	Every capability the account exposes, including endpoints added later

Requests are authorised against the key's permissions the same way a user's are, so a scope that lacks a permission gets 403 on that endpoint rather than a filtered response.

Expiry

Chosen at creation — 30 days, 90 days (default), or longer. Verity marks keys expiring soon within 14 days, stale after 45 days unused, and recommends rotation after 180 days. An expired key authenticates as unauthorised.

Handling keys

• Treat a key as a password: it carries account-wide access under its scope
• Store it in a secret manager, never in source control
• Use a separate key per integration so one can be revoked without disturbing the others
• Prefer account_read unless a write is genuinely needed

Rotation is not automatic

Nothing rotates keys for you. The expiry policy causes a key to stop working, which is a disruption you should schedule rather than discover.