Authentication
Workspace API keys, scopes, environments, and how to keep keys safe.
Every request to /v1 carries a workspace API key as a bearer token, except the four public routes: the service index /, the version index /v1, health at /v1/health, and the contract at /v1/openapi.json.
Authorization: Bearer oai_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1vKeys belong to workspaces
A key is owned by a workspace, not a person. Usage, limits, and billing accrue to the workspace; the key records who created it. Workspace admins create and revoke keys under Settings → API keys in the dashboard. Members can see usage but not manage keys.
Create one key per consumer. "Clay production", "Zapier", and "Local testing" as three keys means you can revoke one without touching the others and read usage per consumer on the usage endpoint.
Key format
| Prefix | Meaning |
|---|---|
oai_live_ | Production key. Reads live data and can queue scans when the scope allows. |
oai_test_ | Reserved for the test tenant, which arrives in a later release. Keys created today are oai_live_. |
The key tag plus the first four characters of the secret (for example oai_live_a1b2) are the key prefix. They are safe to log and appear in the dashboard and in GET /v1/account. The remainder is the secret and is shown once at creation.
Scopes
A key carries a set of scopes chosen at creation. Calling an operation outside them returns 403 forbidden_scope.
| Scope | Grants |
|---|---|
read:stores | Store profiles, enrich without refresh, technologies |
read:signals | History, signal search, event polling (later release) |
write:scans | refresh: true on enrich, explicit scan requests |
read:watchlists, write:watchlists | Watchlist and list operations (later release) |
read:webhooks, write:webhooks | Webhook subscriptions and deliveries (later release) |
read:jobs | Job status and results (later release) |
The dashboard offers three presets: read only, read and watch, and full. Partner integrations get a fixed preset. Check key.scopes on GET /v1/account if a call returns 403.
Revocation and rotation
Revoking takes effect in the dashboard at once, and every API instance rejects the key with 401 unauthorized within 60 seconds. That window is a credential cache, so plan a rotation around it rather than assuming the old key dies on the same request. Revoked keys stay listed in the dashboard for 30 days so usage reports still reconcile.
To rotate, create the new key, deploy it, confirm traffic on the new prefix in the usage view, then revoke the old one. Keys can carry an expiry at creation for credentials you hand to a contractor or a trial.
Keep keys out of browsers
Keys grant workspace-level access and must stay server-side. A browser extension, a spreadsheet add-on, or a no-code tool should call through a backend you control or use the vendor's credential store (Clay, Zapier, and Make all store the key encrypted and send it on your behalf). Never embed a live key in client-side JavaScript.
If a key leaks, revoke it in the dashboard; the leaked key stops working within the same 60-second window. Usage from the leaked key stays attributed to its prefix so you can see what was read.