Skip to main content
The OAuth ES256 token proves identity, but it is never accepted by the B Brands business APIs. When a client needs to read/write B Brands data on behalf of the user, it exchanges its OIDC token for an internal B Brands JWT (the same HS256 format as the traditional login) and uses it as a Bearer. The existing internal authorizer validates it with the user’s own RBAC.
Two different “exchange” endpoints — do not confuse them:
  • POST /api/v3/oauth/exchange → external OAuth client turns an OIDC token into an internal B Brands JWT (this page).
  • POST /api/v3/auth/sso/exchange → internal cross-app session handshake between B Brands apps. See Social login.

​
POST /api/v3/oauth/exchange

Implements a simplified RFC 8693-style token exchange.
​
string
required
The OIDC token issued by the IdP for the user (id_token or access_token).
​
string
Accepted for RFC 8693 parity; not enforced.
​
string
Accepted for RFC 8693 parity; not enforced.

​
What the endpoint does

1

Verify the subject token

ES256 signature against JWKS, plus iss, aud, exp. Rejects expired or invalid tokens with 401.
2

Check the blacklist

If the token jti is blacklisted, reject with 401.
3

Resolve user and client

user_id from sub, client from the https://bbrands.io/client_handle claim. A missing claim returns 401.
4

Validate enablement

The user × platform access must be active and the client must be active. Otherwise 403.
5

Resolve the primary account & mint the JWT

Mint the internal HS256 JWT with user_id, account_id, token_use: "exchange", the client handle and a jti, with a short TTL (default 900s, configurable). Log the issuance with grant_type = token_exchange.

​
Errors

​
Using the exchanged token

The client uses the returned token as Authorization: Bearer ... against the B Brands APIs. The existing internal authorizer validates the HS256 JWT and resolves the user’s own permissions (internal RBAC). The Resource Server does not change.

​
Security notes

The exchanged JWT carries the user’s full permissions in B Brands (no per-client least-privilege). This is acceptable for trusted first-party clients. If scoping is required, introduce it in the exchange (limit the permission set per client).
  • Short TTL is mandatory (default 900s). Never emit the long-lived traditional login token through this flow.
  • The token is revocable via the blacklist by jti. Both this endpoint and the internal authorizer reject blacklisted tokens.
  • There is no refresh for the internal token by design. When it expires, the client re-runs the exchange with a still-valid OIDC token.

​
Machine-to-machine (no user)

For processes without an interactive user (e.g. a sync cron), do not use OAuth or this exchange. Use the existing B Brands API key model, provisioned with least privilege. See Client integration.