Authentication
Create and use CookieBeam API keys, choose scopes, and understand live vs test keys.
The public API authenticates requests with API keys. API access requires a plan that includes the API feature; on a plan without it, a valid key is rejected with a plan_required error (HTTP 403).
Create a key
Key creation is restricted to team owners and is currently arranged with CookieBeam outside the dashboard. Each key has a name, an environment, a list of scopes, and an expiry. Keys always expire: the default is 90 days for live keys and 30 days for test keys, and you can choose any lifetime from 1 to 365 days. A team can have at most 20 active keys.
The full key is displayed exactly once at creation. CookieBeam stores only a SHA-256 hash of the key's validator segment, so a lost key cannot be recovered — revoke it and create a new one.
Key format
Keys are prefixed by environment followed by 64 lowercase hexadecimal characters:
cb_live_<64 hex chars>
cb_test_<64 hex chars>A key that does not match this format, or whose prefix does not match the environment it was created in, is rejected as invalid_key.
Send the key
Send the key as a bearer token in the Authorization header:
Authorization: Bearer cb_live_your_key_hereKeys are team-level principals. A key acts as the team, not as the member who created it, and per-member banner access lists do not restrict key-authenticated requests. Treat keys with the same care as team administrator credentials.
Live vs test keys
Test keys are read-only. Any endpoint that requires a scope ending in :write or :publish rejects a test key with HTTP 403 and the error code test_key_read_only. Use test keys to explore read endpoints without touching production data, and live keys for mutations.
Scopes
Each key carries an explicit allow-list of scopes. An endpoint declares the scopes it requires; if the key is missing one, the request fails with HTTP 403 and the error code missing_scope, with the missing scopes named in the message.
| Scope | Grants |
|---|---|
banners:read | List banners |
banners:write | Create banners |
banners:publish | Publish banner configurations |
consent:read | Read cross-device consent state |
consent:write | Write and delete cross-device consent state |
scanner:read | Read scan results |
scanner:write | Start and manage scans |
analytics:read | Read analytics data |
team:read | Read team information |
team:write | Modify team settings |
webhooks:read | Read webhook configuration |
webhooks:write | Manage webhook configuration |
Grant only the scopes an integration actually uses. A reporting job needs banners:read and nothing else; keep write scopes off keys that ship to CI or shared environments.
Some scopes gate endpoints that are not yet available in the public API. They are listed here because they exist on keys today; see each endpoint page for what is currently reachable.
Authentication errors
All authentication errors use the standard error envelope.
| HTTP status | Code | Cause |
|---|---|---|
| 401 | invalid_key | The key is malformed, unknown, or its prefix does not match its environment |
| 401 | revoked_key | The key has been revoked |
| 401 | expired_key | The key has passed its expiry date |
| 401 | unauthorized | The endpoint requires an API key and none was sent |
| 403 | plan_required | The team's plan does not include API access |
| 403 | missing_scope | The key lacks a scope the endpoint requires |
| 403 | test_key_read_only | A test key was used for a write or publish operation |
Failed authentication attempts are limited to 10 per minute per client IP. Past that budget, further attempts return HTTP 429 with the code rate_limited and a Retry-After header, even if the credentials are wrong. This slows down key guessing; if you see it during legitimate troubleshooting, wait for the window to pass.