Authentication
The connection URL is clean and the same for everyone:OAuth connector (recommended)
OAuth connector (recommended)
Brew is its own OAuth 2.1 authorization server, so most clients connect with no key to copy. Add the URL as a ChatGPT plugin or MCP connection; on first connect the client opens your browser to sign in with Brew and pick a brand, or your whole organization. Brew issues a token scoped to that choice. You can see and revoke it under Settings → MCP, in the “Connected via OAuth” list. This is the first-party flow for ChatGPT, Claude, Grok, Cursor, Codex, VS Code, and the rest. See Connect your client.
API key (alternative)
API key (alternative)
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’s401 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, search_templates, list_flows, and get_flow 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.
Confirmation
On OAuth connections, and on every organization connection, a call that emails people or removes contact data pauses first. Called withoutconfirmed, it returns confirmation_required and does nothing. The result says what would happen (the design and its preview, the recipients, the automation, the addresses or the field) so the user can approve it, plus a confirmation_id. The same call with confirmed: true and that confirmation_id then carries it out. The id holds only for those exact arguments, from the same connection, for 15 minutes, and runs one call, so a call can’t skip the request, an approved call can’t change after the fact, and one approval can’t run twice. Calling again with a used id returns a new confirmation request, except a retry of that same call with the same idempotency_key, which replays its first result. The id doesn’t cover idempotency_key, so a fresh key on the confirmed call keeps it.
The preview shown for a design is Brew’s stored screenshot of it. A design with no screenshot yet comes with its Open in Brew link only.
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.
Safe Retries (Idempotency)
Write tools that support retries accept an optionalidempotency_key (≤ 100 chars), the MCP equivalent of the Idempotency-Key header. Pass it only where the tool’s input schema lists it. Keys are honored identically across the MCP and HTTP surfaces: a write sent over HTTP with Idempotency-Key: k1 and retried with idempotency_key: "k1" here (or the reverse) replays the first result instead of running again. 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 actionablecode, 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:- 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.