Skip to main content

​
Authentication

Every request must carry an Authorization: Bearer <token> header.
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

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