Authentication & Security

Brew uses API key authentication. Each key is scoped to one brand or to your whole organization at creation time, carries a permission scope set, and ships over HTTPS as either an Authorization: Bearer header or the convenience X-API-Key header.

Quickstart

curl -H "Authorization: Bearer brew_your_api_key" \
  https://brew.new/api/v1/domains

import { createBrewClient } from '@brew.new/sdk'

const brew = createBrewClient({ apiKey: process.env.BREW_API_KEY! })
const { data: domains } = await brew.domains.list()

Get a key at brew.new/settings/api.

Headers (Use ONE)

Header	Format	Notes
`Authorization`	`Bearer brew_…`	Recommended. Plays nicely with most HTTP clients + observability tooling.
`X-API-Key`	`brew_…`	Convenience header. Same behavior as the bearer form.

Send exactly one. Sending both is allowed; sending neither returns 401 AUTHENTICATION_REQUIRED. Malformed keys return 401 INVALID_API_KEY; revoked keys return 401 API_KEY_REVOKED.

Brand vs Organization Keys

Every key is scoped when you create it, and the scope can’t change later. It covers either one brand or your whole organization.

	Brand key	Organization key
Reaches	The one brand it was created for	Every brand in the organization
Naming the brand	Nothing to send. The key resolves its brand.	Send `X-Brand-Id: <brandId>` on every brand-scoped request
Brand left out	Works	`400 BRAND_ID_REQUIRED`. There is no default brand.
A different brand named	`403 BRAND_SCOPE_MISMATCH`	Works for any brand in the organization
Create a brand (`POST /v1/brands`)	`403 ORG_SCOPE_REQUIRED`	Works with the `brands` scope

An organization key names its brand on each request:

curl -H "Authorization: Bearer brew_your_org_key" \
  -H "X-Brand-Id: kx7b3s7fapqz8mjm12ekz1kxdx87yceg" \
  https://brew.new/api/v1/domains

Find brand ids with GET /v1/brands. An organization key sees every brand there. A brand key sees only its own, so the same call tells any key which brand it can reach. These rules hold for both kinds:

X-Brand-Id is a header, and it is the only way to name a brand. No endpoint accepts a brandId field in a body or query string. Sending one returns 400 INVALID_REQUEST with param: "brandId".
Reads return only the resolved brand’s data, and writes change only that brand. An identifier from another brand returns 404 (not 403), so the API never confirms that a resource exists elsewhere. An X-Brand-Id naming a brand outside your organization returns 404 BRAND_NOT_FOUND for the same reason.
Organization-level endpoints take no X-Brand-Id: /v1/brands (brand lifecycle), GET /v1/templates (the public template catalog), GET /v1/flows (public email flows), and GET /v1/usage. The no-auth discovery surfaces, GET /v1/health and GET /v1/help, are not brand-scoped either. Every other authenticated endpoint is brand-scoped.

Use a brand key when an integration only ever touches one brand. If it leaks, the damage stays inside that brand. Use an organization key for tooling that works across brands, like a script that creates brands. A brand can have any number of keys (dev, staging, production, per-service, per-teammate). Organization and brand credentials owns this contract in full: which operations are organization-level, when you get 400 BRAND_ID_REQUIRED, 403 BRAND_SCOPE_MISMATCH, or 403 ORG_SCOPE_REQUIRED, and how that differs from 403 INSUFFICIENT_ROLE.

Permission Scopes

Each key carries one or more permission scopes. Routes require either the route’s scope or all. Missing permission returns 403 INSUFFICIENT_PERMISSIONS with error.param pointing at the missing scope name.

Scope Implication (Coarse Scopes Satisfy Granular Ones)

Brew supports both coarse scopes (contacts, emails, automations) and granular least-privilege scopes (audiences, domains, sends). A coarse scope automatically satisfies the granular scopes it implies, so existing keys keep working. You only reach for the granular scopes when you want to lock a key down further.

Granted scope	Satisfies
`contacts`	`contacts`, `audiences`
`emails`	`emails`, `domains`, `sends`
`automations`	`automations`
`all`	everything
each granular scope (`audiences`, `domains`, `sends`)	itself only (least privilege)
`brands`	itself only. No other scope implies it, so an existing key never gains the right to create brands.

The complete set of valid scope values accepted when a key is created is contacts, emails, automations, audiences, domains, sends, brands, transactional, and all.

Per-Route Required Scope

A trailing * covers every method and nested route under that path prefix.

Route	Required scope (or an implier)
`/v1/contacts`, `/v1/fields`, `POST /v1/audiences/from-events`	`contacts`
`/v1/audiences*` (other than `from-events`)	`audiences` (or `contacts`)
`/v1/domains*`	`domains` (or `emails`)
`/v1/emails`, `/v1/email-groups`, `/v1/templates`, `/v1/flows`	`emails`
`/v1/sends*` (including `{ test: true }`)	`sends` (or `emails`)
`/v1/brand*`, `/v1/usage`	`emails`
`/v1/analytics/overview`, `/v1/analytics/events`	`emails`
`/v1/analytics/automations`	`automations`
`/v1/automations` (incl. `/triggers`, `/runs`, `/audience-runs`, `/trigger-instances`), `/v1/payload-contracts/infer`	`automations`
`/v1/content/*`, `/v1/chats/{chatId}`	`emails`
`POST /v1/brands`	`brands`, on an organization key
`GET /v1/brands*`, `GET /v1/integrations`	any scope
`POST /v1/data`	set per table: `db ls` lists the tables the key’s scopes reach
`/v1/api-keys*`	none: a signed-in dashboard session only (see Key Lifecycle)
`/v1/health`, `/v1/help`	none: no authentication

transactional is a reserved scope with no route today. Principle of least privilege. For a back-end that only fires triggers, issue a key with automations only: even if it leaks, it can’t list contacts. For a service that only inspects send health, issue emails because the analytics reads require that scope; the key still cannot manage contacts or automations. The dashboard surfaces each key’s scope set so you can audit + rotate.

Key Lifecycle

Action	Where
Create	Dashboard → API Keys. Choose one brand or the whole organization, then a scope set; the secret is shown ONCE, store it in your secret manager.
List	Dashboard. The list shows the key id, prefix, scope, brand binding, and last-used timestamp. The full secret is never re-exposed.
Rotate	Dashboard. Create a fresh key with the same scope set; cut traffic over (zero-downtime); revoke the old key after a grace window.
Revoke	Dashboard. Revoked keys immediately return `401 API_KEY_REVOKED` on every request.
Audit	Dashboard surfaces the last-used timestamp per key. Pair with your platform’s request logs (e.g. Vercel) for full attribution via `x-request-id`.

Key CRUD is not part of the programmatic surface. The three /v1/api-keys operations you see in the API reference back the dashboard’s own API page: they accept only a signed-in Clerk session whose active organization role is exactly org:admin. An API key, an OAuth connection, the MCP server, and the CLI all receive 403 on them, so a compromised key can never mint or revoke another. If you need programmatic key management for a SOC2 / SAST pipeline, contact us.

Production Security Checklist

Practice	Why
Keys live in environment variables on the server only. Never in client JS, mobile binaries, or git.	A key in the browser can be exfiltrated and used against your brand.
Use short-lived deploys’ env vars + a secret manager. Vercel + Vault / Doppler / 1Password / AWS Secrets Manager all work.	Centralised rotation, audit trail.
One key per environment. Separate dev / staging / prod keys.	Blast radius: revoke staging without touching prod.
One key per service when feasible. Webhook receiver gets a key; cron worker gets a different key.	Granular audit + rotation.
Set `Idempotency-Key` on every retried `POST` so a replayed key burst doesn’t double-fire.	See Idempotency.
Honor `Retry-After` on `429`.	See Rate limits.
Log every API call’s `x-request-id` from the response.	Support diagnostics; correlate end-to-end through Brew’s pipeline.
Pin to the official TypeScript SDK when possible (`@brew.new/sdk@latest`).	Auto-retries, auto-idempotency keys, typed error envelope.
Verify webhook signatures (when outbound webhooks ship).	See Webhooks & events.

What We Do NOT Support Today

For transparency:

OAuth 2.0 / token exchange for end-user authorization. The Brew Public API is server-to-server today; if you want per-user OAuth on top of the API, build it in your app and hold the Brew key on your server. Contact us if you have a use case that genuinely needs OAuth.
PATCH request idempotency. See Idempotency for the supported methods and replay contract.
Public key-management API. The /v1/api-keys operations require an org:admin dashboard session, so keys are minted, rotated, and revoked from the dashboard, never by another key.

These are roadmap items where there’s customer pull; tell us at the link below if your integration needs any of them.

Errors

Authentication failures and permission errors use the standard envelope and codes documented in Errors.

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:

Self-Service Tools
Talk to Our Team

Search Documentation

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

ChatGPT/Claude Integration

Click “Open in ChatGPT” at the top right of any page to explore it further with ChatGPT or Claude.

Overview

Core concepts

Guides

MCP server

CLI

Public API v1

Quickstart

Headers (Use ONE)

Brand vs Organization Keys

Permission Scopes

Scope Implication (Coarse Scopes Satisfy Granular Ones)

Per-Route Required Scope

Key Lifecycle

Production Security Checklist

What We Do NOT Support Today

Errors

See Also

Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

​Quickstart

​Headers (Use ONE)

​Brand vs Organization Keys

​Permission Scopes

​Scope Implication (Coarse Scopes Satisfy Granular Ones)

​Per-Route Required Scope

​Key Lifecycle

​Production Security Checklist

​What We Do NOT Support Today

​Errors

​See Also

​Need Help?

Search Documentation

ChatGPT/Claude Integration

Schedule a Call

Call Us Directly

Slack Channel

Email Support

Quickstart

Headers (Use ONE)

Brand vs Organization Keys

Permission Scopes

Scope Implication (Coarse Scopes Satisfy Granular Ones)

Per-Route Required Scope

Key Lifecycle

Production Security Checklist

What We Do NOT Support Today

Errors

See Also

Need Help?