Authentication & Security

Brew Public API v1 authentication, permission scopes, key lifecycle, brand binding, and production security best practices.

Brew uses API key authentication. Each key is bound to exactly one brand 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 Binding (One Brand per Key)

Every API key is bound to exactly one brand at creation time. The binding is enforced server-side:

• The brand id is resolved from the key on every request: clients never send a brandId field. Sending one returns 400 INVALID_REQUEST with param: "brandId".
• All brand-scoped reads filter to the key’s brand automatically. Cross-brand identifiers surface as 404 (not 403) so the API never confirms the existence of resources in another brand.
• All brand-scoped writes target only the key’s brand.

The lone organization-wide endpoint is GET /v1/templates (the public template catalog). Every other endpoint is brand-scoped.

To operate on a different brand, switch brands in the dashboard at brew.new/settings/api and create a new key for that brand. A brand can have any number of keys (dev, staging, production, per-service, per-teammate); each acts on the same single brand it was created against.

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)

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

Per-Route Required Scope

Route	Required scope (or an implier)
/v1/contacts, /v1/contacts/search, /v1/fields	contacts
/v1/audiences (all methods)	audiences (or contacts)
/v1/domains (all methods)	domains (or emails)
/v1/emails, /v1/emails/import, /v1/templates	emails
/v1/sends (POST, incl. { test: true }), /v1/sends/{sendId}/cancel	sends (or emails)
/v1/brand, /v1/usage	emails
/v1/analytics/campaigns, /v1/analytics/events, /v1/analytics/sends	emails
/v1/analytics/automations, /v1/analytics/trigger-instances	automations
/v1/automations (incl. /triggers*, /runs*)	automations

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 sends (it can read /v1/analytics/sends but not generate emails or manage domains). The dashboard surfaces each key’s scope set so you can audit + rotate.

Key Lifecycle

Action	Where
Create	Dashboard → API Keys. Choose a brand and 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.

There is no API for key CRUD today: provisioning is human-in-the-loop through the dashboard so a compromised key can’t mint more. 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 idempotency. The Idempotency-Key header is honored only on POST. PATCH operations are naturally idempotent at the resource level, so re-sending the same body is safe.
• Public key-management API. Keys are minted from the dashboard.

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

Errors

Code	HTTP	When
AUTHENTICATION_REQUIRED	401	No Authorization / X-API-Key header.
INVALID_API_KEY	401	The key doesn’t parse (e.g. wrong prefix).
API_KEY_REVOKED	401	The key was revoked in the dashboard.
INSUFFICIENT_PERMISSIONS	403	The key’s scope set doesn’t include the route’s required scope. error.param carries the missing scope name.

See Errors for the full error envelope + every code in the catalog.

See Also

• API introduction: the overview that links every reference page.
• Idempotency: set Idempotency-Key on every retried POST.
• Rate limits: per-route policies + the 429 cookbook.
• SDK authentication: TypeScript SDK auth specifics.

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

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 analyze documentation with ChatGPT or Claude for deeper insights.

Talk to Our Team

Schedule a Call

Book time with our founders for personalized guidance on strategy, best practices, or complex implementation questions.

Call Us Directly

Need immediate assistance? Reach us at [phone] for urgent issues or time-sensitive questions.

Slack Channel

Our preferred support channel. You’ll receive an invite after signup for direct founder support and fast responses.

Email Support

Contact us at [e-mail] for detailed inquiries or if you prefer not to use Slack.