> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.cope-demo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Use a Bearer API key from the COPE vendor dashboard or a Clerk bearer token to authenticate every request.

# Authentication

Every request must carry an `Authorization: Bearer <token>` header.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer ck_live_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Public API keys are the default for vendor integrations. Clerk bearer tokens are also accepted when a first-party or embedded client needs to call the same public API surface.

## Key format

New keys use the format `ck_live_<prefix>_<secret>`.

| Component     | Value                                                            |
| ------------- | ---------------------------------------------------------------- |
| Type and mode | `ck_live` (constant)                                             |
| Prefix        | 12-character alphanumeric identifier, safe to display            |
| Secret        | 48 lowercase hexadecimal characters, shown only once on creation |

Keys issued earlier in the format `cope_sk_live_<key_id>_<secret>` keep working unchanged. You do not need to replace them.

Live keys produce real side effects. Test-mode keys are reserved for the future public sandbox and are not accepted yet.

## Clerk tokens

When using a Clerk bearer token, include the business ID explicitly:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Bearer eyJhbGciOi...
X-Cope-Business-Id: <business-id>
```

COPE verifies that the Clerk user belongs to the requested business before forwarding the request. Clerk requests without `X-Cope-Business-Id` return `401 business_required`.

## Getting a key

1. Sign in to the COPE vendor dashboard.
2. Open **Settings → API Keys**.
3. Click **Create API key**, give the key a name, and copy the secret token that appears.
4. The secret is shown **only once** — store it securely. It cannot be retrieved later.

## Rotation and revocation

* Issue a new integration, switch the client to the new key, then deactivate the previous one from the same dashboard view.
* Deactivated and deleted keys stop authenticating within 60 seconds.
* Keys are scoped to one business. Use separate integrations for separate businesses rather than sharing a key across them.
* Clerk tokens are scoped by the `X-Cope-Business-Id` header after ownership validation.

## Failure modes

| Response code               | Meaning                                                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `401 missing_authorization` | `Authorization` header missing or malformed.                                                                                                                                   |
| `401 invalid_token_format`  | Bearer payload is neither a valid COPE API key (`ck_live_<prefix>_<secret>`, or `cope_sk_live_<key_id>_<secret>` for a key issued earlier) nor a supported Clerk bearer token. |
| `401 invalid_token`         | Key not found, deactivated, the secret does not match the stored digest, or test mode was requested before sandbox support is enabled.                                         |
| `401 business_required`     | Clerk token was valid, but `X-Cope-Business-Id` was missing.                                                                                                                   |
| `403 business_forbidden`    | Clerk token was valid, but the user does not belong to the requested business.                                                                                                 |