Authentication

Every /v1 request carries a bearer key:

Authorization: Bearer vnd_live_...

There is no cookie fallback and no CSRF token on this surface — an API key is not a browser credential, so the attacks those defend against do not apply. Requests without a valid key are refused before routing.

Scopes

A key holds an explicit set of resource:action scopes, chosen at issue time. Each endpoint requires exactly one.

Scope	Covers
vendors:read / vendors:write	vendor register, bulk import
contracts:read / contracts:write	contracts, contract documents, downloads
controls:read	controls, control mappings
evidence:read / evidence:write	control evidence, uploads, downloads
risks:read / risks:write	risk registers (read), risk scenarios (read + write)
incidents:read / incidents:write	incident register and filing
policies:read	policies and policy versions
compliance:read	compliance posture, framework detail
audit:read	the audit log feed
webhooks:read / webhooks:write	outbound webhook management
trust-center-content:read	Trust Center resources
trust-center-access:read	Trust Center access requests, visitor tokens
trust-center-subscribers:read	Trust Center subscribers
inbound-questionnaire:read / :write	the browser-extension surface

Every operation in the API reference names the one scope it requires. That page is generated from the service, so it is the list to trust if this table ever falls behind it.

Missing scope is 403. An invalid, revoked or expired key is 401.

Note

A key can never exceed the permissions of the person who issued it. Scopes are validated against the issuer’s own role at creation, so an analyst cannot mint a key that does what an administrator can. It also means a key can outlive the issuer’s access: review keys when someone changes role or leaves.

What a key is not allowed to do

Two limits are worth knowing before you design around them, because both are deliberate and neither will be lifted by asking:

• A key cannot read evidence flagged sensitive. That content is restricted to its uploader, administrators and auditors — named people. A key is nobody in particular, so listings return those rows with their descriptive fields redacted and the download returns 403. The attempt is written to the audit trail. A key can file sensitive evidence.
• A key names exactly one organization. There is no “switch organization” on this surface. An integration spanning several organizations holds one key per organization.

Rotation

Issue the new key, deploy it, then revoke the old one — a client can hold several valid keys at once, so rotation needs no downtime. Revocation takes effect immediately on the next request.

Keys may also carry an expiry. An expired key fails closed with 401; nothing warns you first, so put the expiry date in the same place you keep the key.

The 401 that is really a 404

Key authentication runs before routing, so a request to a /v1 path that does not exist is rejected by the authenticator — 401 UNAUTHORIZED, “Invalid API key” — byte-identical to a real endpoint hit with a bad key.

This is intentional: an unauthenticated caller cannot map the surface by probing. The cost is a misleading error during development. If a call returns 401 and the key demonstrably works elsewhere, check the path in the API reference before you debug credentials.