Authentication: API keys, scopes and OAuth
How to authenticate to the Bridge to Brands REST API with bearer API keys and to the MCP server with API keys or OAuth 2.1, plus scopes and brand allowlists.
REST API: bearer API keys
Every request carries Authorization: Bearer b2b_live_<prefix>_<secret>. The REST API accepts API keys only.
| Scope | Grants |
|---|---|
read |
brands, catalog, availability, lookup, ship-tos, own usage |
orders |
place, read and acknowledge orders |
A key can also carry a brand allowlist, an expiry and an IP allowlist.
| Status | Meaning |
|---|---|
401 |
unknown, revoked or expired key |
403 |
the key lacks the scope or the brand is not on its allowlist |
429 |
rate limited; honour Retry-After |
MCP server: API key or OAuth 2.1
The MCP server at https://mcp.brdg2b.ai/mcp accepts, in order:
Authorization: Bearer b2b_live_…: a raw API key (Claude Code, the Claude Messages API, Claude.ai request headers where enabled).Authorization: Bearer <jwt>: an access token issued by brdg2b’s OAuth 2.1 server (ChatGPT, Claude.ai sign-in). Tokens are short-lived (1 hour) with rotating refresh tokens.- Nothing or invalid:
401withWWW-Authenticate: Bearer resource_metadata="https://mcp.brdg2b.ai/.well-known/oauth-protected-resource"so compliant clients discover the authorization server.
OAuth uses PKCE (S256), the code and refresh_token grants and Dynamic Client Registration. On the consent screen you sign in with Google and choose which API key the client acts as, or mint a new one. Every OAuth token is bound to a key, so usage is attributed to it and revoking the key disconnects the client.
What keys can never do
Portal credentials, key management, members and the cross-key usage dashboard live under the web app only. A leaked API key cannot read or change a portal password or mint more keys.