Skip to main content

​
Authentication

The connection URL is clean and the same for everyone:
There are two ways to authenticate it.

OAuth connector (recommended)

For clients with no OAuth UI, or headless / CI setups, send an API key as a bearer token instead. A brand key gives a brand connection, and an organization key gives an organization connection:
Create keys at Settings → API. A request with no or invalid credential returns 401; OAuth-capable clients use its challenge to begin discovery.

​
OAuth Discovery and Security

Compatible clients discover authentication from Brew’s 401 WWW-Authenticate challenge and protected-resource metadata. Brew publishes RFC 8414 authorization-server metadata (plus the OIDC discovery fallback), supports Dynamic Client Registration for public clients, and requires Authorization Code + PKCE S256. Redirect URIs are exact-match registered, web callbacks require HTTPS, and loopback HTTP remains available for desktop clients. The only public scope is brew:all. Authorization and refresh requests are bound to the exact resource audience https://brew.new/api/mcp; unknown scopes and audience mismatches are rejected. Access tokens are short-lived, refresh tokens rotate, and reusing an already-rotated refresh token revokes that grant. Brew does not advertise Client ID Metadata Documents (CIMD).

​
Brand Scoping

A connection covers either one brand or your whole organization, and there is no brand in the URL. With OAuth you choose when you sign in. With an API key, the key’s scope decides which kind you get. get_brew_capabilities reports which kind of connection you have. Brand connection. Every tool acts on the bound brand, so leave brand_id out. Passing a different brand fails with BRAND_SCOPE_MISMATCH rather than touching the wrong brand. To work on another brand, disconnect and connect again picking it, or use that brand’s key. Organization connection. There is no default brand. Every brand-scoped tool requires brand_id, and leaving it out returns BRAND_ID_REQUIRED. Call list_brands for the ids, and ask the user which brand they mean when it isn’t clear. Organization-level tools such as list_brands, create_brand, list_templates, and list_flows take no brand_id. An OAuth connection has the access of the person who connected it. An organization admin reaches every brand, and a member reaches only the brands they were added to. An organization API key reaches every brand. Find brand details with the get_brand tool or in the dashboard. Authentication covers how brand and organization keys work over the API.

​
Send Confirmation

On OAuth connections, and on every organization connection, send_email pauses before a real send. Call it without confirmed and Brew returns confirmation_required instead of sending, so an agent can surface the recipient count and get approval first. Call again with the same inputs plus confirmed: true to release it. A real run_automation launch pauses the same way. Brand API-key connections are meant for programmatic use and do not pause at this gate. Get approval before the first real send_email call, and make it once. Test sends (test: true) and run_automation dry runs never pause.

​
Safe Retries (Idempotency)

Every write tool accepts an optional idempotency_key (≤ 100 chars), the MCP equivalent of the Idempotency-Key header. Keys are honored identically across the MCP and HTTP surfaces. Idempotency owns the replay window, conflict behavior, and key patterns. Always pass one on send_email. That tool is fail-closed. If dedupe cannot be guaranteed it refuses with a retryable 503 rather than risk a double send.

​
Errors & Observability

Errors surface with an actionable code, message, suggestion, and a request_id you can quote to support. Out-of-credits → INSUFFICIENT_CREDITS. Permission gaps and validation failures each return a distinct code.

​
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.

ChatGPT/Claude Integration

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