Skip to main content
Every Brew credential answers two separate questions before an operation runs. What can it reach? is the credential’s scope: one brand, or the whole organization. Who is asking? is the person’s role. The two produce different 403 codes, and no amount of permission scopes fixes either one.

​
Two Kinds of Credential

A key is bound when you create it in Settings → API: choose one brand, or the whole organization. Keys are made, rotated, and revoked there only; see Key Lifecycle. No v1 endpoint accepts a brand in a body or query string.

​
Naming the Brand

There is no default brand. An organization-scoped credential that omits X-Brand-Id on a brand-scoped operation gets 400 BRAND_ID_REQUIRED, not a guess. Discover the ids with GET /v1/brands, which returns every brand in the organization for an organization-scoped credential and exactly the one bound brand for a brand-bound key.
A brand-bound key may omit the header. If it sends one naming a different brand, that is 403 BRAND_SCOPE_MISMATCH: use the brand it is bound to, or switch to an organization-scoped key. A brand id from outside the organization is 404 BRAND_NOT_FOUND, so the API never confirms that another organization’s resources exist.

​
Organization Operations

A few operations act on the organization itself, not on a brand. They take no X-Brand-Id, and a brand-bound key cannot call the ones that write or bill:

​
403 ORG_SCOPE_REQUIRED

A brand-bound key calling an organization operation gets:
This is about the credential’s binding, not its permission list. A brand-bound key holding all still gets ORG_SCOPE_REQUIRED on GET /v1/usage. The fix is to mint an organization-scoped key at brew.new/settings/api (create the key without choosing a brand) and use that one for billing and brand-directory reads. Over MCP, reconnect at the organization level instead of picking a single brand.

​
403 INSUFFICIENT_ROLE

A person, rather than a key, can fail for a different reason: they do not hold the access the operation needs. error.param says which: INSUFFICIENT_ROLE and ORG_SCOPE_REQUIRED are not interchangeable. Minting an organization-scoped key does not grant a person a role, and granting a role does not re-bind a key. A third code, 403 INSUFFICIENT_PERMISSIONS, is the only one that a different scope set on the key fixes; see Authentication for the scope table.

​
Key Management Is Session-Only

The three /v1/api-keys operations back the dashboard’s own API page and accept only a signed-in org:admin session, so a leaked key can never mint or revoke another one. Key Lifecycle owns the rule.

​
Choosing a Scope

  • One product, one brand. Use a brand-bound key. It cannot touch another brand even if it leaks, and it never has to send a header.
  • An agency, a platform, or anything multi-brand. Use an organization-scoped key and pass X-Brand-Id per request. Read GET /v1/brands once at startup and cache the mapping.
  • Billing dashboards and provisioning. Use an organization-scoped key: GET /v1/usage and POST /v1/brands accept nothing less.

​
Need Help?

Our team is ready to support you at every step of your journey with Brew. Choose the option that works best for you:

Search Documentation

Type in the “Ask any question” search bar at the top left to instantly find relevant documentation pages.

Ask ChatGPT or Claude

Click here to open the Copy page menu at the top of this page, then send the page to ChatGPT, Claude, or your editor.