> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cope.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 cope_sk_live_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxx
```

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

| Component | Value                                           |
| --------- | ----------------------------------------------- |
| Prefix    | `cope_sk` (constant)                            |
| Mode      | `live` or `test`                                |
| Key ID    | 8-character public identifier                   |
| Secret    | Random secret tail, shown only once on creation |

Live keys produce real side effects. Test-mode keys are reserved for the future public sandbox and currently return `401 invalid_token`.

## 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 keys return `401 invalid_token` on the next request.
* 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_sk_<mode>_<key_id>_<secret>` API key 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.                                                         |