insufficient_scope

Your key is valid, but it does not have the scope this route needs.

HTTP 403

When you see this

Each route requires one scope. Canopy checks it after the key authenticates and after the rate-limit check. So your key is real and within its rate limit. It was never given the permission this route needs.

If the token itself is invalid, you get unauthorized instead. insufficient_scope only appears once the key is known to be real.

What the response looks like

json

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key does not have the required scope for this route: payment_intents:create.",
    "detail": { "requiredScope": "payment_intents:create" },
    "request_id": "req_1a2b3c4d5e6f7a8b9c0d1e2f",
    "docs": "https://canopypay.io/errors/insufficient_scope"
  }
}

The response names the missing scope in the message and in detail.requiredScope.

What to do

Use a key that has the scope. Retrying with the same key fails the same way.

Every route on /api/v1 requires payment_intents:create. A key with that scope can create, list and read intents, read their origins, and issue their source inbox. Every key Canopy issues today has this scope. If you see this error, the key is older than the scope, or its scope list was set to something narrower.

Replace the key, do not rotate it

Rotating a key does not add scopes. Rotation copies the old key's scopes, so it can never widen what a key can do. Issue a new key instead. New keys get the current default scopes.

If the error continues with a new key, check that the key belongs to the right account.