> ## Documentation Index > Fetch the complete documentation index at: https://docs.bbrands.io/llms.txt > Use this file to discover all available pages before exploring further. # Flows > End-to-end sequence diagrams for interactive sign-in, consuming B Brands APIs, token refresh and user provisioning. This page walks through every runtime flow with sequence diagrams. Endpoint details are in [Endpoints](/oauth/endpoints) and [Token exchange](/oauth/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. ```mermaid theme={null} sequenceDiagram actor U as User participant O as Client app participant G as auth.bbrands.io (issuer, protocol endpoints) participant A as auth.bbrands.io (consent UI) participant S as OIDC engine participant H as Access-token hook participant AM as Identity store U->>O: Click "Sign in with B Brands" O->>U: Redirect to /api/v3/oauth/authorize?client_id&redirect_uri&scope&state&code_challenge U->>G: GET /api/v3/oauth/authorize (PKCE) G->>G: Resolve client metadata, log intent G->>A: 302 → /oauth/consent?...&authorize_url&client_handle&trust_level A->>A: Check B Brands session → user_id alt No session A->>U: Redirect to /auth/login?next= end alt first_party + enabled A->>G: POST /api/v3/oauth/decision (approve, audit) A->>S: Redirect to authorize_url (auto-approve) else third-party U->>A: Allow / Deny A->>G: POST /api/v3/oauth/decision A->>S: Redirect to authorize_url (or redirect_uri?error=access_denied) end S->>O: Redirect to redirect_uri?code&state O->>G: POST /api/v3/oauth/token (code + PKCE verifier) G->>S: Forward to engine token endpoint S->>H: Trigger access-token hook H->>AM: Re-check enablement (status active) H->>S: Return claims (iss/aud rewritten, identity + account profile) S->>G: access_token + refresh_token + id_token (ES256) G->>O: Forward tokens (proxied) O->>O: Validate id_token vs JWKS, get/create user, set session O->>U: Logged in (the client app applies its own permissions) ``` `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. ```mermaid theme={null} sequenceDiagram participant O as Client backend participant G as api.bbrands.io participant AM as Identity store participant R as Blacklist store Note over O: Has a valid OIDC token for the user O->>G: POST /api/v3/oauth/exchange { subject_token } G->>G: Verify OIDC token (ES256 vs JWKS, iss, aud, exp) G->>R: jti blacklisted? G->>AM: user × platform access(user, client) = active? alt Enabled G->>G: Mint internal JWT (HS256, short TTL, jti) G->>O: { token, token_type, expires_in, account } O->>G: GET /api/v3/ (Bearer internal JWT) G->>G: Validate HS256 + RBAC G->>R: jti blacklisted? G->>O: Data (scoped to the user's permissions) else Not enabled / inactive client G->>O: 403 Forbidden end ``` 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](/oauth/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. ```mermaid theme={null} sequenceDiagram participant O as Client app participant G as auth.bbrands.io (issuer) participant S as OIDC engine participant H as Access-token hook participant AM as Identity store O->>G: POST /api/v3/oauth/token (grant_type=refresh_token) G->>S: Forward S->>H: Trigger hook H->>AM: Re-check user × platform access (status) alt Suspended / revoked / client suspended H->>S: Throw S->>G: 400 invalid_grant G->>O: Error → client logs the user out else Enabled H->>S: Identity claims (iss/aud rewritten) S->>G: New tokens G->>O: Tokens end ``` ## 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. ```mermaid theme={null} sequenceDiagram actor A as Admin participant AM as Identity admin console participant DB as Identity store participant Q as Provisioning queue participant W as Webhook worker participant O as Client API A->>AM: Enable access user=Jane, client=erp-prod AM->>DB: Create user × platform access (status=active) DB->>Q: Trigger enqueues provisioning event (pending) Q->>W: Worker picks job W->>O: POST /provision (HMAC signed: identity + status) O->>O: Create/update user; assign its own groups O->>W: 200 OK W->>DB: Mark event delivered ``` Failure handling: `2xx` → `delivered`; `4xx` → `failed` (no retry); `5xx`/timeout → exponential backoff retry, then `dead_letter` + alert. See [Data model](/oauth/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](/oauth/social-login). ```mermaid theme={null} sequenceDiagram actor U as User participant A as Authentication app participant G as api.bbrands.io participant S as OIDC engine participant GG as Social provider U->>A: Click "Continue with social provider" A->>G: GET /api/v3/auth/login/oauth/ G->>S: signInWithOAuth(provider) S->>GG: OAuth redirect GG->>S: Callback (tokens) S->>G: /callback#access_token&refresh_token G->>G: setSession + ensure registration + login G->>A: Internal B Brands JWT (HS256) + account data A->>U: Logged in (session cookie / internal handshake) ```