Skip to main content

Token Exchange Model

Summary​

Token exchange enables organizational context switching by replacing the current access token with a new one scoped to a different department assignment. During the exchange, the platform revokes the previous token and creates a session-bound organization ticket linking the session to the new context. This ensures that only one organizational context is active per session at any time.

Why It Exists​

Users with assignments in multiple departments need to switch context without re-authenticating. A user assigned to both Engineering and Finance departments can move between these contexts within a single session. Token exchange provides this capability while maintaining a clean authorization boundary — each token reflects exactly one department context, and the previous token becomes invalid upon switching.

Where It Fits in Keymate​

Token exchange connects the organization model (which defines department assignments) to runtime authorization (which consumes token claims). When a user selects a department, the exchange mechanism produces a new token whose claims reflect that assignment. Downstream services and the Access Gateway then use these claims for authorization decisions. The session governance layer tracks the session's active context through the organization ticket.

Boundaries​

This page covers department context switching via token exchange. It does not cover:

How It Works​

Context Selection​

The user selects a department assignment from their available assignments. This selection triggers the token exchange flow. The platform validates that the user holds an active assignment to the requested department before proceeding.

Organization Ticket Creation​

The platform creates a session-bound organization ticket that records the link between the current session and the selected department assignment. This ticket serves as the persistent record of which context the session is operating in. If a previous ticket exists for the session, the platform replaces it.

Token Revocation​

The platform revokes the current access token. This is a critical step — the previous token becomes invalid immediately. Any service that introspects the old token after this point receives an inactive response. This prevents the user from holding valid tokens for multiple department contexts simultaneously.

New Token Issuance​

The platform issues a new access token with claims derived from the selected department assignment. The new token carries the department context, associated roles, and projected attributes for that assignment. The session continues with this new token as the active credential.

Single Active Context​

Only one organizational context is active per session at any time. The combination of token revocation and ticket replacement enforces this constraint. A user cannot hold valid tokens for two departments simultaneously within the same session.

Diagram​

Example Scenario​

Scenario​

A user currently operating in the Engineering department needs to review budget data that requires Finance department context. The user switches department context through the application interface.

Input​

  • Actor: Authenticated user with assignments to both Engineering and Finance departments
  • Resource: Token exchange endpoint
  • Action: Switch context from Engineering to Finance
  • Context: Active session with a valid Engineering-scoped token

Expected Outcome​

  • Applied — The platform creates a new organization ticket for the Finance assignment, revokes the Engineering-scoped token, and issues a new token with Finance department claims
  • Why: The user holds a valid assignment to Finance, so the exchange succeeds. The Engineering token is no longer valid, and all subsequent requests use the Finance-scoped token

Common Misunderstandings​

  • "The original token remains valid after exchange" — No. The platform revokes the previous token during the exchange. Introspecting the old token returns an inactive response. This is a deliberate security measure to enforce single active context.

  • "Users can hold tokens for multiple departments simultaneously" — No. The revocation step ensures that only one department-scoped token is valid per session at any time.

  • "Switching departments requires re-authentication" — No. Token exchange replaces the token within the existing session. The user retains their authentication state; only the organizational context changes.

warning

The platform revokes the previous token during exchange, not after. Any service caching the old token must handle the case where introspection returns inactive and prompt the client to use the new token.

Design Notes / Best Practices​

  • Design client applications to handle token replacement gracefully. After a context switch, all subsequent API calls must use the new token.
  • Use enhanced introspection at the Access Gateway to catch requests that still carry a revoked token after a context switch.
  • Store the active department context in client-side session state so the UI reflects the current context immediately after exchange.
tip

When integrating token exchange into a frontend application, treat the exchange response as a full token refresh. Replace stored tokens and update any cached authorization state.

  • Multi-department users switching between organizational contexts during a workday
  • Applications that restrict data visibility based on the active department in the token
  • Audit scenarios tracking which department context was active during specific operations

Token Claims & Context

Claim structure of the tokens produced by exchange

Session Governance

How sessions track organizational context through tickets

Organization Model

Department assignments that drive context switching

Logout Model

Session termination that invalidates tokens