Authentication
Every request authenticates with a secret API key sent in the x-api-key header:
Your organization and workspace are bound to the key at creation and resolved server-side on every request. You never send — and never receive — an organization or workspace ID.
API keys are server-to-server credentials. Never embed a key in a browser, mobile app, or any client a customer can inspect, and never commit it to source control. If a key is exposed, revoke it immediately and rotate.
Key format
Keys look like cpk_<random> — a single cpk_ prefix followed by a random body that carries ~256 bits of entropy and
a short trailing checksum. The checksum lets obviously-malformed keys be rejected before any lookup and helps
secret-scanners detect a leaked key. Only a masked prefix (cpk_ plus the first four characters, e.g. cpk_ab12…) and
the last four characters are ever shown after creation.
The raw key is returned exactly once, when you create or rotate it. Store it in your secrets manager immediately — it cannot be retrieved again.
Managing keys
Keys are managed in the Respona app under Settings → API Keys: create, list, revoke, rotate, set a per-key monthly credit limit, and configure the IP allowlist. Each mutation is recorded in an append-only audit trail.
Scopes
Keys carry a scope set. Two presets cover the common cases:
A key without the required scope for an endpoint is rejected with 403 (INSUFFICIENT_SCOPE) — distinct from a
missing or invalid key, which is 401.
IP allowlist
A key may optionally be restricted to a set of source IPs or CIDR ranges. Requests from outside the allowlist are
rejected with 403 (IP_BLOCKED), even if the key is otherwise valid. Leave the allowlist empty to allow any source.
Rotation with overlap
Rotate keys on a schedule and whenever one may have leaked. Rotating returns a new raw key and automatically schedules the old key to expire after a grace window (24 hours by default). Both keys stay valid during the window, so you can deploy the replacement and confirm traffic has moved before the old key stops working — rotation is a routine operation rather than an outage. If a key is known to be compromised, revoke it immediately instead of waiting out the window.
Failure reference
See Errors for the full envelope and code table.