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"
  }
}