Skip to main content

Token Exchange Model

Summary​

Organization-context switching produces a fresh token set after the server recomputes eligibility and updates the requesting authenticated client session. Public browser clients use same-realm authorization-code + PKCE re-entry. Approved confidential clients and BFFs can use the planned privileged exchange profile.

Token replacement in the client and automatic server-side invalidation of an already issued access token are different guarantees. The generic contract requires explicit access/refresh rotation behavior and does not claim that an old self-contained access token is revoked because a new token was issued.

Planned capability

The generic browser runtime and confidential-client exchange are planned in KEOPS #307 and #308. Customer-specific implementations are references, not the generic product contract described here.

Why It Exists​

Applications need a controlled way to change organization context without trusting a client-provided membership identifier or mixing credentials from different contexts. The exchange model recomputes current eligibility, isolates the change to the requesting client session, and defines how the client replaces its token state.

Where It Fits in Keymate​

The organization-context model defines eligible contexts and the minimal token claim. Authentication flows establish the initial client session. This model defines the browser and confidential-client profiles that change that session's selected context, while the authorization layer resolves current access for the selected context.

Boundaries​

This page covers context-switch request profiles, server-side revalidation, client-session isolation, and token rotation responsibilities. It does not claim that:

  • selecting another context deletes or disables the previous membership;
  • issuing a replacement token automatically revokes an earlier self-contained access token;
  • one client can overwrite a sibling client's selected context; or
  • a public browser can hold a confidential-client secret.

Shared Server-Side Rules​

Both switching profiles must:

  1. Resolve the requesting client to its Keymate Application binding.
  2. Recompute eligible contexts through the canonical KEOPS orchestrator.
  3. Reject stale, disabled, expired, cross-realm, cross-tenant, or application-unavailable selections.
  4. Update only the requesting AuthenticatedClientSessionModel.
  5. Issue a fresh token set with a minimal, versioned org_context claim.
  6. Emit audit data without storing raw tokens.

The server never trusts an earlier selector payload as proof of current eligibility.

Public Browser Profile​

Public SPAs and browser clients use authorization-code + PKCE re-entry:

The browser does not hold a confidential-client secret and does not call the privileged exchange directly.

Confidential Client or BFF Profile​

An approved confidential client authenticates itself and requests a canonical target context using the planned exchange capability. The server validates subject token/session, issuer, audience, authorized party, scopes, token type, and client policy before recomputing eligibility.

On success, the BFF must atomically:

  • replace its server-side access token;
  • replace or rotate its refresh token according to the response contract; and
  • rotate its own HttpOnly application-session cookie.

A partial client-side update can mix old and new contexts, so the application-session update is part of the consumer contract.

Old-Token Policy​

The generic contract separates four facts:

  • A fresh access token is issued.
  • The client must stop presenting the old access token.
  • Refresh capability is rotated according to the selected runtime profile.
  • The old access token is not automatically revoked unless the deployment explicitly implements and enforces that policy.

JWT signature and expiry validation alone cannot observe that a membership, client-session context, or durable role fact changed after issuance. Immediate or near-real-time rejection requires an enforcement mechanism such as supported introspection, session-state validation, denylisting, or sufficiently short token lifetime. The chosen profile must be documented and tested end to end.

Client-Session Isolation​

Context belongs to the requesting authenticated client session, not to the root SSO session. If Jane uses applications X and Y under one SSO login, X can select organization A while Y keeps organization B. Switching X must not overwrite Y's context or tokens.

Membership Lifecycle Is Separate​

Disabling or removing membership A makes A ineligible and, under the planned KEOPS lifecycle fix, removes durable role assignments anchored to A. It does not:

  • remove another active membership B;
  • select B automatically for every client;
  • rewrite tokens already issued for A; or
  • terminate the root SSO session unless a separate session policy says so.

See Org-Aware Tokens & Sessions for the complete lifecycle matrix.

Example Scenario​

Scenario​

Jane's BFF currently stores an A-context token set. Jane requests B:

Input​

  • Actor: Jane through an approved confidential BFF
  • Resource: Organization-scoped application access
  • Action: Change the BFF client session from organization A to organization B
  • Context: B remains active and eligible when the server reevaluates the request

Expected Outcome​

  1. The BFF authenticates itself and submits B's canonical context reference.
  2. The server recomputes eligibility and updates only the BFF's client session.
  3. The server returns a fresh B-context token set.
  4. The BFF atomically replaces token state and rotates its application cookie.
  5. Jane's sibling browser client remains on its own context.
  6. The BFF never presents the old A token again, even though that token's server-side invalidation depends on the configured enforcement profile.

Common Misunderstandings​

  • "Every browser should call token exchange with a client secret." Public browsers use authorization-code + PKCE re-entry.
  • "Issuing a new token automatically revokes the old JWT." Not in the accepted generic contract.
  • "The selected context is global to the SSO session." It is scoped to the requesting authenticated client session.
  • "A context switch can trust the choices rendered earlier." Eligibility is recomputed on submission and exchange.
  • "Switching organization deletes the old membership." Selection and membership lifecycle are separate commands.

Design Notes / Best Practices​

  • Use authorization-code + PKCE re-entry for public browser clients.
  • Restrict the privileged exchange profile to approved confidential clients.
  • Replace the complete client-side or BFF token state atomically after a successful switch.
  • Document whether the deployment relies on expiry, introspection, denylisting, or session-state validation for old-token rejection.
tip

Treat a successful context switch as an atomic application-session update: persist the new access token, refresh capability, and application cookie together.

  • A browser changes organization context without handling a client secret.
  • A BFF exchanges to another eligible organization and rotates its server-side token state.
  • Two sibling clients keep independent organization contexts under one SSO login.
  • A service enforces current membership state before an earlier token expires.

Token Claims & Context

Minimal versioned context projection and authorization boundaries.

Session Governance

Root and client-session lifecycle.

Org-Aware Tokens & Sessions

Context selection and membership-role lifecycle.

Logout Model

Explicit session termination behavior.