Skip to main content

Bearer API keys

Bearer API keys are client-scoped credentials sent in the Authorization header as a Bearer token: Authorization: Bearer <API_KEY>. Unlike Standard keys, a Bearer key belongs to your account (not a single user), and can be rotated, revoked, or expired independently.

Bearer keys come in two types — both use the same Bearer format described below and differ only in what they are permitted to do:

  • Full access — can call every route your account is entitled to.
  • Scoped — limited to an explicit allowlist of routes and/or presets.

Every request also needs the shared Client Header (CLIENT-ID), the correct Environment URL, and — where required — the signature headers. The CLIENT-ID must match the account the key belongs to.

Authorization Header​

Required Keys

  • API_KEYREQUIREDString

    A Bearer API key (full-access or scoped) you create in the Keys section (API Auth Credentials).


Authorization Header
AUTHORIZATION: 'Bearer `API_KEY`'

This is how your headers should look:

Headers
CLIENT-ID: 'your_client_id'
AUTHORIZATION: 'Bearer vrfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Key types: full access vs scoped​

When you create a Bearer key you choose its type:

  • Full access — the key can call every route your account is entitled to. Simple, but broad; treat it like a password.
  • Scoped — the key is limited to an explicit allowlist of routes and/or presets (bundles of related routes). Requests to any other route are rejected with a 403.
  • Expiry (optional) — either type can be given an expiration date, after which it stops working automatically.

If a request uses a scoped key that is missing a required route, the API returns 403 Not Authorized. If the key itself is missing, revoked, or expired (either type), the API returns 401.

Verify a key​

SDKs and integrations can confirm a key is usable and check exactly what it grants by calling the verify endpoint with the key itself. This works for both full-access and scoped keys:

Verify the calling key
curl https://api.veryfi.com/api/v1/partner/settings/api-keys/verify \
  -H "CLIENT-ID: your_client_id" \
  -H "AUTHORIZATION: Bearer your_api_key"

It returns 401 when the key is missing, revoked, or expired; otherwise it returns the routes and presets the key grants, plus its expiry. (A full-access key reports the complete set of routes it can reach.)

Managing Bearer keys​

Create, list, rotate, and revoke both full-access and scoped keys in the Keys section of the Hub, or programmatically. See Bearer API Key Management.

A key can also carry its own webhook URL that overrides your account-level webhook for async requests made with that key — see Per-key webhook URL.