Send machine credentials in a header
API clients send Authorization: Bearer followed by the secret. Keys beginning sk_test_ belong to the sandbox; keys beginning sk_live_ belong to production. The environment is part of key ownership, not a request parameter a caller can use to switch access.
A key’s scopes limit its permitted actions. Source discovery uses sources:read, screening uses screenings:write, and result access uses results:read. Batch, monitoring, case, usage, and webhook actions have their own scopes. Only give a machine the scopes its job needs.
Create, rotate, and revoke keys
Authorized humans create keys in the dashboard. The secret is shown once and only secure verification material is retained. To rotate, create a replacement, update and verify the server integration, then revoke the old key. Revoked credentials fail authentication rather than falling back to an anonymous or demo identity.
Never embed production keys in browser code, URLs, source control, analytics, or logs. Human sessions use WorkOS AuthKit and server-side organization membership checks. Key management and team administration require human permissions; an API key does not impersonate an account owner.
Handle authorization failures deliberately
Treat 401 as an authentication problem and 403 as an authorization problem. Stop retries that cannot succeed without changing credentials or permissions. Record the request ID and error code for support, without logging the secret or submitted subject. Recovery, verification, MFA, and invitation delivery depend on the operator’s configured WorkOS environment.
KEEP BUILDING