Company scoping

A key authenticates at the tenant level, but most resources belong to a company. The effective company for a request is resolved with a layered fallback.

Resolution order

1. The X-Company-Id request header (highest precedence).
2. The key's default_company_id, if one is configured on the key.
3. Your tenant's single active default company.

curl https://your-app.example.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_PUBLICID.SECRET" \
  -H "X-Company-Id: 0190abcd-1234-7000-8000-000000000000"

When no valid company resolves

If none of the three sources yields a company — or the one named by the header (or the key default) is not an active company in your tenant (unknown, archived, or belonging to another tenant) — the request fails with 422 and the invalid_company code:

{
  "error": {
    "code": "invalid_company",
    "message": "company … is not an active company in this tenant",
    "requestId": "0190abcd-1234-7000-8000-000000000000"
  }
}