This page walks through every runtime flow with sequence diagrams. Endpoint
details are in Endpoints and
Token exchange.
1. Interactive sign-in (user signs into a client app)
The user clicks “Sign in with B Brands” in a client app. The IdP authenticates
them and the client app receives identity tokens. The client app then applies
its own authorization.
POST /api/v3/oauth/decision only audits the consent decision. The actual
OAuth code continuation is performed by the engine via authorize_url.
2. Consuming the B Brands APIs (token exchange)
When the client needs to read/write B Brands data on behalf of the user, it
exchanges its OIDC token for an internal B Brands JWT and uses it as a
Bearer. The B Brands APIs authorize it with the user’s own RBAC.
Do not confuse POST /api/v3/oauth/exchange (external OAuth client → internal
JWT) with POST /api/v3/auth/sso/exchange (internal cross-app session
handshake between B Brands apps). See Token exchange. 3. Token refresh with re-validation of enablement
Refresh re-runs the access-token hook, so a user disabled after issuance stops
getting new tokens.
4. Provisioning via webhook
Enabling access in the identity admin console fires a webhook that pre-creates
the user in the target platform. The payload carries identity + status, never
roles.
Failure handling: 2xx → delivered; 4xx → failed (no retry); 5xx/timeout
→ exponential backoff retry, then dead_letter + alert. See
Data model for the event lifecycle.
5. End-user social login (separate system)
The social login for B Brands’ own end users is a different system from the
OAuth IdP for external clients. It uses the managed engine’s social provider
directly and is covered in Social login.
