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.

If the key is limited to a list of companies, the header must name one of them and the key's default is always one of them. With neither, the tenant default is used when the key may use it, and otherwise the first active company on the key's list.

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