unauthorized

HTTP 401

When this happens

Authentication runs on every /api/v1/* request, ahead of anything else about it. Two conditions produce this code.

• The Authorization header is absent, or present but not in the exact form Authorization: Bearer <token>. The message reads "A bearer token is required."
• A token was extracted but does not authenticate: it is unrecognized, revoked, or a publishable key rather than a secret key. The message reads "The bearer token is invalid, revoked, or not a secret key." See the credentials guide for the exact prefix each key type uses.

The second case is the one integrators hit most often. The publishable key is meant for the browser, as the merchant field passed to the checkout SDK's mount(), and the secret key is meant for server-to-server calls to this API. Passing the publishable key as the bearer token lands here rather than on a more specific error.

The error envelope

{
  "error": {
    "code": "unauthorized",
    "message": "The bearer token is invalid, revoked, or not a secret key.",
    "request_id": "req_1a2b3c4d5e6f7a8b9c0d1e2f",
    "docs": "https://canopypay.io/errors/unauthorized"
  }
}

param is never present on this error. There is no single request field to blame; the whole credential is wrong.

What to do about it

Confirm the request sends Authorization: Bearer <secret key> with your secret key, not the publishable one. If the key was recently rotated or revoked, mint a fresh one and update the caller.

Rotation keeps the predecessor live only through its own overlap window, and a revoked key never authenticates again. This is a client-side fix; retrying the identical request will fail identically.