Skip to main content

Token Claims & Context

Summary​

Access tokens issued by Keymate carry structured claims that encode the caller's identity, active organizational context, effective roles, and custom attributes. The platform assembles these claims from the user's profile, the active department assignment (recorded as an organization ticket), and attribute definitions configured for token visibility. This claim structure enables stateless authorization at every service boundary.

Why It Exists​

Downstream services need a consistent, verifiable view of the caller's identity and permissions without making secondary lookups to a central authority. A well-defined claim model ensures that every service in the request chain can evaluate authorization decisions locally using the information embedded in the token itself.

Where It Fits in Keymate​

Token claims sit at the intersection of identity, organization membership, and authorization. The organization model defines the hierarchy of tenants and departments. The identity model provides the user profile. Token issuance combines these inputs into a claim set that the authorization layer and downstream services consume. Enhanced introspection validates that the claims remain current by checking department access and session state at query time.

Boundaries​

This page covers the structure and assembly of token claims. It does not cover:

How It Works​

Standard Identity Claims​

Every access token includes baseline identity claims: the subject (user identifier), issuer (authorization server), audience (intended recipient services), and expiry. These follow standard token conventions and allow any service to verify token authenticity and freshness.

Organizational Context Claims​

When a user selects a department assignment, the platform creates a session-bound organization ticket that links the session to the chosen assignment. Claims derived from this ticket — including the active tenant, department, and assignment reference — are projected into the access token. This gives downstream services the organizational context needed to scope data access and enforce tenant boundaries.

Role Claims​

The token carries effective roles derived from multiple levels: tenant-level roles, department-level roles, and roles from the specific user assignment. The platform resolves the applicable role set at token issuance and embeds the result as role claims. Services use these to perform role-based authorization checks without querying the role hierarchy at request time.

Custom Attribute Projection​

Administrators can mark specific attribute definitions for token visibility. When an attribute definition has token projection enabled, the platform includes the attribute's current value in the token claims at issuance time. Attributes not marked for projection remain in the user profile but do not appear in the token, keeping the token size manageable and limiting exposure of sensitive data.

Introspection-Based Validation​

The platform provides enhanced token introspection that goes beyond standard token validation. When a service introspects a token, the platform checks whether the user still has a valid assignment to the department encoded in the token and verifies that the underlying session remains active. If the assignment has been revoked or the session has been terminated, introspection returns an inactive response — even if the token has not yet expired. This enables near-real-time access revocation without waiting for token expiry.

Diagram​

Example Scenario​

Scenario​

A backend service receives a request from a user who switched to the Finance department. The service needs to verify the caller's department and roles before returning financial data.

Input​

  • Actor: Authenticated user with an active Finance department assignment
  • Resource: Financial report endpoint on a downstream service
  • Action: Read financial data
  • Context: Access token carrying Finance department context and associated roles

Expected Outcome​

  • Granted — The downstream service reads the department and role claims from the token, confirms the caller has the required role for financial data access, and returns the report
  • Why: The token carries the organizational context and role claims assembled at issuance, enabling the service to authorize the request locally without additional lookups

Common Misunderstandings​

  • "All user attributes appear in tokens" — Only attributes with token projection explicitly enabled in their definitions appear in the token. Unprojected attributes remain in the user profile and are not included.

  • "Token claims remain valid until expiry" — Enhanced introspection can mark a token as inactive before its expiry if the underlying department assignment or session has been revoked.

  • "Downstream services must call the authorization server for every request" — Token claims enable local authorization decisions. Introspection is used for revocation checks, not for every request.

warning

Token claims reflect the state at issuance time. If you need to detect mid-session revocation of department access, use enhanced introspection rather than relying on claim values alone.

Design Notes / Best Practices​

  • Enable token projection only for attributes that downstream services require for authorization decisions. Fewer projected attributes reduce token size and limit data exposure.
  • Use enhanced introspection at trust boundaries (such as the Access Gateway) rather than at every internal service hop to balance security with performance.
  • Treat organization ticket binding as the source of truth for organizational context — the ticket links the session to the active department assignment.
tip

Configure the Access Gateway to perform enhanced introspection on inbound requests. This catches revoked assignments and terminated sessions before requests reach downstream services.

  • Scoping data access by department in multi-tenant services
  • Enforcing attribute-based access control using projected custom attributes
  • Detecting revoked department access in near-real-time via introspection

Token Exchange Model

How context switching replaces the current token with a department-scoped one

Session Governance

Session hierarchy, external mapping, and cascade termination

Organization Model

Tenant and department hierarchy that tokens reference

Authorization

Policy evaluation that consumes token claims