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 a brand-scoped API key as a bearer token instead:
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

Every connection is scoped to exactly one brand, and there is no brand in the URL. With OAuth you choose the brand when you sign in; with an API key the key itself carries its brand. There are no organization-scoped API keys. Either way the token or key determines the brand for every call. This holds on organization accounts too. Connecting from one shows a brand picker, and you select the single brand that connection will use. To work on a different brand, disconnect the MCP connection and connect again, picking the other brand. With an API key, use that brand’s key instead. Find brand details via the get_brand tool or the dashboard.

​
Send Confirmation

On OAuth connections 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. 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) 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.