Org-Aware Tokens & Sessions
Summary
Keymate embeds organizational context into access tokens through a token exchange mechanism that binds a user's session to a specific department assignment. When a user selects an organizational context, the platform creates a session-bound ticket and issues a new token containing organizational claims. Downstream services read these claims to determine the user's active Tenant, department, and roles without additional lookups.
Why It Exists
In a multi-tenant platform, a valid authentication token alone does not tell downstream services which organizational context the user is operating in. A user may belong to multiple Tenants and departments. Without organizational claims in the token, every downstream service would need to query the user's assignments independently — increasing latency, coupling, and complexity. Org-aware tokens solve this by embedding the active organizational context directly into the access token.
Where It Fits in Keymate
Org-aware tokens connect the Membership & Application Assignment model (which defines user assignments) to runtime authorization. After a user authenticates, they select an organizational context, which triggers the token exchange flow. The resulting token carries claims derived from the selected assignment, including roles from the Delegated Administration hierarchy. Downstream services and the Policy Evaluation Model consume these claims.
Boundaries
What this concept covers:
- The token exchange flow for embedding organizational context
- Organization tickets (session-bound assignment references)
- Token revocation on department switch
- Organizational claims in access tokens
What this concept does not cover:
- Token validation and gateway processing — see Token & Session
- Policy evaluation using token claims — see Policy Evaluation Model
- How user assignments are created — see Membership & Application Assignment
How It Works
Organizational Context Selection
After authentication, a user with multiple assignments selects which organizational context to operate in. This selection identifies a specific Tenant and department assignment. If the user has a default assignment, the platform can apply it automatically when no explicit selection is made.
Organization Ticket
When the user selects an organizational context, the platform creates an organization ticket — a session-bound record that links the user's active session to the selected assignment. The ticket persists for the duration of the session and serves as the authoritative reference for the user's current organizational context.
Token Exchange
The platform performs a token exchange: the current access token is replaced with a new one that contains organizational claims derived from the selected assignment. These claims include the active Tenant, department, and the effective roles resolved from the Delegated Administration hierarchy (Tenant-level, department-level, and user-assignment-level roles).
Token Revocation on Department Switch
When a user switches to a different department or Tenant context, the platform revokes the previous token before issuing a new one. This ensures that only one organizational context is active at a time and prevents stale organizational claims from being used.
Downstream Consumption
Downstream services read organizational claims directly from the access token. These claims provide the Tenant context, department context, and effective roles without requiring the service to query the organizational model. This enables stateless authorization decisions at the service level.
Diagram
Example Scenario
Scenario
A user with assignments in two departments switches from Engineering to Finance context during an active session.
Input
- Actor: Jane Doe (
user@example.com), authenticated with an active session - Resource: Two department assignments — Engineering and Finance within Acme Corp
- Action: Switch organizational context from Engineering to Finance
- Context: Jane's current token carries Engineering department claims and roles
Expected Outcome
- Result: The platform revokes Jane's current token, creates a new organization ticket for the Finance assignment, and issues a new token with Finance department claims and roles
- Why: The token exchange ensures that downstream services see the Finance context. The revoked token can no longer be used, preventing authorization decisions based on stale Engineering claims.
Common Misunderstandings
- "Users can hold tokens for multiple departments simultaneously." — No. The token exchange revokes the previous token before issuing the new one. Only one organizational context is active per session at a time.
- "Organizational claims are added to the existing token." — No. The platform performs a full token exchange, replacing the existing token with a new one. This ensures all claims in the token are consistent with the selected context.
- "Downstream services must query the organizational model." — The purpose of org-aware tokens is to eliminate this need. Organizational claims in the token provide the full context downstream services require.
Token revocation on department switch means the previous token becomes invalid immediately. Downstream services holding a cached reference to the old token will receive authorization failures. Design clients to handle token refresh gracefully.
Design Notes / Best Practices
- Design client applications to handle token exchange seamlessly — prompt the user to select a context when they hold multiple assignments, and refresh API connections after a switch.
- Use the default assignment to minimize friction for users who primarily operate in a single organizational context.
- Read organizational claims from the token at the service boundary rather than maintaining local state about the user's organizational context.
Combine org-aware tokens with the Policy Evaluation Model for authorization decisions that consider the user's active organizational context — including department-specific roles and attributes.
Related Use Cases
- Embedding department context into tokens for downstream microservice authorization
- Enabling users to switch between department assignments during an active session
- Building a department-aware API that reads organizational claims from the access token