What is the Access Token Relay pattern?
The gateway authenticates the incoming request and forwards a signed token, usually a short-lived JWT, that carries the user's identity and permissions. Each service verifies the signature with the issuer's public keys and checks the claims it cares about. Service-to-service calls pass the token on, or exchange it for one scoped to the next hop.
What problem does the Access Token Relay pattern solve?
If every service calls a central session store on every request, that store becomes a bottleneck and a single point of failure. If services trust any internal request, one compromised service can do anything. A signed token lets each service check who the caller is without a network call.
How do you implement the Access Token Relay pattern?
- Authenticate at the gateway and issue or forward a signed access token.
- Have services fetch and cache the issuer's public keys (JWKS) and verify every token.
- Check issuer, audience, expiry and the specific scopes or roles each endpoint needs.
- Keep tokens short-lived and use token exchange to narrow scope for downstream calls.
- Authenticate the services themselves too, for example with mutual TLS.
When should you use it?
- Several services need to know who the end user is and what they may do.
- You want authorization decisions made inside each service, not only at the edge.
When should you avoid it?
- You need immediate revocation on every call. Self-contained tokens stay valid until they expire.
What do you gain?
- No central lookup on every call
- Each service enforces its own rules
- Identity is available everywhere for auditing
What does it cost?
- Revocation is delayed until expiry
- Key rotation must be handled carefully
- Large tokens add overhead to every request
What are common mistakes with the Access Token Relay pattern?
- Checking only at the gateway, so internal services trust any request that reaches them.
- Long-lived tokens that cannot be revoked in practice.
- Putting sensitive data in token claims, which are readable by anyone who holds the token.
Access Token Relay in practice
Keystone Identity
Every internal service looked up the caller's session in a central store on every request. During a traffic spike the session store became the bottleneck for the whole platform.
The gateway now validates the user's token once and forwards a signed, short-lived JWT. Each service verifies the signature locally with cached public keys and checks the scopes it needs.
Example decision record
- Context
- Checking the session store on every internal hop adds latency and load to a single shared component.
- Decision
- Validate tokens at the gateway and relay signed, short-lived tokens that services verify locally.
- Consequences
- Services verify callers without calling a central store.
- Tokens must be short-lived because revoking them before expiry is hard.