Authentication

Bearer keys

Send your secret in the Authorization header on every request. There is no other authentication mechanism for the public API.

Authorization: Bearer proval_sk_…

The key identifies the organization the request acts on, so you never pass an organization ID explicitly. A missing or unrecognised key returns 401.

Keys are server-side only. Anyone holding the secret can create sessions and read identity results for your organization. Never ship one to a browser, a mobile binary, or a public repo. The browser-facing half of a verification uses the short-lived session URL returned by POST /verifications, not your API key. That URL embeds the session secret, so it is a bearer credential for that one session: give it to the user it belongs to and to nothing else, logs included.

Scopes

Each key carries an explicit list of scopes. A call whose scope is missing returns 403, not 401. The key was recognised, it just isn't allowed to do that.

Grant the narrowest set that works. A backend that only kicks off verifications needs write:sessions and read:sessions and nothing else.

One key per service

There is no separate sandbox environment today. Every key is a live key, and calls made with it run against production infrastructure. Issue a distinct key per service and per deployment anyway: it means you can revoke one without taking everything else down, and the dashboard's usage view tells you which service is making which calls.

The SDKs accept an environment option. It currently resolves to the same host either way, so treat it as forward-compatibility rather than isolation.

Expiry

A key can be created with an expiry measured in months from its creation date. Once past it, every call with that key returns 401. There is no grace period and no warning in the response of earlier calls. If you set an expiry, put a calendar reminder to roll the key before it lands.

Leave expiry unset for a key that should not expire.

IP allowlists

A key can be restricted to a list of source IPs. A request from any other address is rejected with 403 even when the secret is correct.

Read this before you count on it. The check compares against the first address in the X-Forwarded-For header, falling back to the socket address when the header is absent. That header is supplied by the caller, so anyone holding a stolen secret can send an allowlisted address in it and pass the check from anywhere. The allowlist is an operational guardrail: it catches a key that has been copied into the wrong service or a script running from the wrong network, and it narrows accidental use. It is not a barrier against someone who has your secret and has read this page. The controls that actually contain a leaked key are the scopes on it, its expiry, and deleting it.

If your traffic leaves through a NAT gateway or egress proxy, allowlist that address, not your application servers'. Matching is exact, so list each address. CIDR ranges are not expanded.

Rotating a key

The secret is displayed once, when the key is created. It is stored only as a hash, so it genuinely cannot be shown again. If you lose it, roll the key.

Rolling issues a new secret for the same key record, preserving its scopes and settings. To rotate without downtime:

1. Create a second key with the same scopes.
2. Deploy it to your services and confirm traffic is flowing on the new secret.
3. Delete the old key.

Rolling in place invalidates the old secret immediately, so use the two-key approach for anything with live traffic.

If a key is exposed, delete it first and reissue second. A deleted key stops working immediately.

Checklist

• Secret lives in an environment variable or secret manager, never in source control.
• Scopes are the minimum the service actually needs.
• Separate keys per environment, and ideally per service.
• IP allowlist set if your egress addresses are stable, remembering it is a guardrail rather than a barrier.
• A documented owner who knows how to roll it at 3am.