examples · errors · 10 / 19

10. 403 - token valid but for a different instance

what this error means

The bearer is well-formed and not expired, but it does not authorise the tenant in the URL. OriginChain tokens are scoped to a single instance - sending one tenant's token to another tenant's endpoint returns 403, never reveals whether the other tenant exists.

what triggers it

A token for tenant A used against tenant B's URL.

POST /v1/tenants/:other/sql

curl -X POST "https://$OC_HOST/v1/tenants/other-tenant/sql" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT 1"}'

the canonical response body

{
  "error": "forbidden",
  "message": "token does not authorise access to tenant 'other-tenant'",
  "retry": false
}

how to recover

Confirm the tenant id in the URL matches the tenant the token was issued for.
If you genuinely need to call the other tenant, issue a token from that tenant's dashboard.
Multi-tenant apps should key the token off the tenant before constructing the URL - never the other way around.
retry: false - same token, same URL, same answer.

common upstream causes

Tenant id hardcoded in a snippet that was copied between environments.
Staging token used against a production endpoint.
Tenant id and instance hostname out of sync after a rename.
Multi-tenant app router building the URL from one source and the token from another.
Token scope was narrowed (e.g. read-only) and the call needs a permission the scope doesn't grant.