> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.respona.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.respona.com/_mcp/server.

# Authentication

Every request authenticates with a secret API key sent in the `x-api-key` header:

```bash
curl https://api.respona.com/rest/api/v1/orders/123 \
  -H "x-api-key: cpk_your_key_here"
```

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.

> **Warning**
>
> 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:

| Preset        | Grants                         | Use for                                                |
| ------------- | ------------------------------ | ------------------------------------------------------ |
| `FULL_ACCESS` | `ORDERS_READ` + `ORDERS_WRITE` | Creating, launching, and reading orders.               |
| `READ_ONLY`   | `ORDERS_READ`                  | Polling / reporting integrations that must not mutate. |

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

| Condition                      | HTTP  | `code`               |
| ------------------------------ | ----- | -------------------- |
| Missing or malformed key       | `401` | `UNAUTHENTICATED`    |
| Expired or revoked key         | `401` | `UNAUTHENTICATED`    |
| Valid key, missing scope       | `403` | `INSUFFICIENT_SCOPE` |
| Source IP not on the allowlist | `403` | `IP_BLOCKED`         |

See [Errors](/guides/api-conventions/errors) for the full envelope and code table.