A support engineer is helping the broker u-broker-n1 with a failed quote. The engineer copies the access token that the portal backend sends to the quote API, pastes it into a decoder, and is surprised twice. First, everything is readable: the broker's id, the tenant brk-north, the scope quotes.read quotes.submit. "I thought tokens were encrypted." Second, out of curiosity, the engineer edits the scope to add uw.decide, re-encodes the middle part, and sends the result to the quote API. It is refused before the API even looks at the scope.
Both surprises have the same cause, and this page is about it. A token of this kind is signed, not hidden: anyone can read it, and any change to it breaks the signature. A third fact surprises people later and costs more. Suppose the unedited token reaches the API and passes every check. That still settles only who is calling. Whether this broker may read quote Q-6620, which belongs to another brokerage, is a separate decision. A valid token is not a permission.
What a token is, in plain words#
After the broker signs in, the identity provider writes a short statement: "this is u-broker-n1 of tenant brk-north, allowed to call the quote API with quotes.read and quotes.submit, until 09:15". It signs the statement so that the quote API can check it came from the identity provider and was not changed. The portal backend presents that statement on every API call.
That statement is a token: a string a server issued that carries or points to claims. Each statement inside it is a claim, a name and a value such as "tenant": "brk-north". The one who wrote and signed it is the issuer (iss, here https://idp.insurer.example). The service it is meant for is the audience (aud, here https://api.uw.insurer.example). An access token is the kind a client presents to an API to be let in; an ID token tells a client who signed in; a refresh token gets new access tokens from the issuer. This page is mostly about access tokens.
Most access tokens on the web today are bearer tokens. Standard (RFC 6750, read 2026-11-18): a bearer token is "A security token with the property that any party in possession of the token" can use it. A tiny example: whoever holds the broker's token string can call the API as the broker until it expires. Possession is the proof. That one sentence explains most of the rules below.
Before AI. A backend engineer knows two older shapes of the same idea. A servlet session id is a reference: it means nothing until the server looks it up. A SAML assertion or a Kerberos ticket is a signed statement: the receiver checks the signature and reads the content. JWT access tokens are the second kind; opaque tokens checked by introspection are the first. Spring's resource server filter, which validates a bearer token before the controller runs, is the pre-AI version of everything on this page.
The smallest token: one real demo token, part by part#
The example in examples/uw-auth/ issues demo tokens. They have the exact shape of a JWT signed with HMAC-SHA256, made with the Python standard library and keys that say they are not secrets. They are teaching tokens, not production cryptography: use a maintained library and an identity provider in production. Here is the access token the identity provider stand-in issues for the broker at the example's clock start, 2026-11-18T09:00:00Z (tokens.issue_for("u-broker-n1", aud=tokens.API_AUD, now=NOW)):
eyJhbGciOiJIUzI1NiIsImtpZCI6ImRlbW8tMjAyNmEiLCJ0eXAiOiJKV1QifQ
.eyJhdWQiOiJodHRwczovL2FwaS51dy5pbnN1cmVyLmV4YW1wbGUiLCJjbGllbnRfaWQiOiJzdmMtcG9ydGFsLWJmZiIsImV4cCI6MTc5NDk5MzMwMCwiaWF0IjoxNzk0OTkyNDAwLCJpc3MiOiJodHRwczovL2lkcC5pbnN1cmVyLmV4YW1wbGUiLCJqdGkiOiJqdGktYThkYTRjYmNiZmQ2IiwibmJmIjoxNzk0OTkyNDAwLCJwcmluY2lwYWxfdHlwZSI6InBlcnNvbiIsInJvbGVzIjpbImJyb2tlciJdLCJzY29wZSI6InF1b3Rlcy5yZWFkIHF1b3Rlcy5zdWJtaXQiLCJzdWIiOiJ1LWJyb2tlci1uMSIsInRlbmFudCI6ImJyay1ub3J0aCJ9
.OTGz0evl6OCkv-jb32et3InJgPoLPHAuu4mP3nWXSAU
It is one line in reality; it is broken at the two dots here. Three parts, each base64url-encoded. Base64url is an encoding, not encryption, which is the support engineer's first surprise.
Part 1, the header, says how the token was protected:
{"alg": "HS256", "kid": "demo-2026a", "typ": "JWT"}
alg names the signature algorithm, kid names which key signed it (the "current" demo key; demo-2026b is the next one), typ says what it is.
Part 2, the payload, is the claims, readable by anyone who holds the token:
{
"aud": "https://api.uw.insurer.example",
"client_id": "svc-portal-bff",
"exp": 1794993300,
"iat": 1794992400,
"iss": "https://idp.insurer.example",
"jti": "jti-a8da4cbcbfd6",
"nbf": 1794992400,
"principal_type": "person",
"roles": ["broker"],
"scope": "quotes.read quotes.submit",
"sub": "u-broker-n1",
"tenant": "brk-north"
}
sub is the subject, iat/nbf/exp are issued-at, not-before and expiry in epoch seconds (900 seconds of life here, illustrative), and jti is this token's unique id. client_id is the portal backend that requested it. principal_type, roles and tenant are this example's own claims.
Part 3, the signature, OTGz0evl..., is HMAC-SHA256 over the exact bytes part1 + "." + part2, with the key named by kid. Change one character of part 2 and the signature no longer matches. That is the engineer's second surprise.
Now the names. Token format (RFC 7519, read 2026-11-18): a JWT (JSON Web Token) is "A string representing a set of claims as a JSON object that is encoded in a JWS or JWE." A JWS (JSON Web Signature, RFC 7515) is "A data structure representing a digitally signed or MACed message", with the three-part compact form above. A JWE (JSON Web Encryption, RFC 7516) is "an encrypted and integrity-protected message", five parts in compact form. Almost every access token you will meet is a JWS. Guideline (OWASP JWT Cheat Sheet, read 2026-11-18): "Signed JWTs are not confidential"; leave privacy-sensitive data out of the token, or use JWE when claims must be secret.
Common confusion. A JWT is a token format, not a login protocol. Something has to authenticate the person and issue the token (OAuth and OpenID Connect, next page). The format only says how the claims are packed and protected.
The ordered checks a resource server makes#
The quote API receives that token in an Authorization: Bearer header (Standard, RFC 6750: clients "SHOULD" use the header, "Resource servers MUST support this method", and tokens "SHOULD NOT be passed in page URLs"). Before believing a single claim, it runs checks in a fixed order. The order matters: the claims are written by whoever made the token, so nothing in them counts until the signature proves the issuer made it.
examples/uw-auth/tokens.py verify() makes the checks visible. The snippet demonstrates the order and the meaning of each check on the broker's token. A successful run proves only that this demo token is genuine and meant for the quote API; it says nothing about any record.
import demo_keys
import tokens
from clock import START_EPOCH_S as NOW
tok = tokens.issue_for("u-broker-n1", aud=tokens.API_AUD, now=NOW)
result = tokens.verify(tok, keyset=demo_keys.keyset(), expected_issuer=tokens.ISSUER,
expected_audience=tokens.API_AUD, now=NOW)
for check in result["checks"]:
print(f"{check['name']:<10} {check['passed']!s:<5} {check['detail']}")
print("valid:", result["valid"], "|", result["note"])
Run in a scratch copy of the example on 2026-11-18 (the example's agent is a scripted stand-in, so results here show how the access controls work, not how good any model is):
format True three base64url parts; header and payload are JSON objects
alg True alg HS256 is on the allowlist (HS256)
kid True kid demo-2026a is in the verifier's key set
signature True HMAC-SHA256 with demo key demo-2026a matches
iss True iss is https://idp.insurer.example
aud True aud is https://api.uw.insurer.example
exp True exp 1794993300, now 1794992400
nbf True nbf 1794992400, now 1794992400
revocation True jti jti-a8da4cbcbfd6 is not on the revocation list
valid: True | authentication only: a valid token is not a permission; the policy decision point decides the action
Each line has a standard behind it:
| Check | Rule (standard) | What it stops |
|---|---|---|
alg on an allowlist | RFC 8725: "Libraries MUST enable the caller to specify a supported set of algorithms"; RFC 7518: implementations "MUST NOT accept Unsecured JWSs by default" | alg: none, and a token that chooses a weaker or confusable algorithm |
kid known | RFC 7515: kid is "a hint indicating which key was used"; the verifier picks from its own key set | keys named or supplied by the token itself |
| signature | RFC 8725: "All cryptographic operations used in the JWT MUST be validated" | any change to header or claims |
iss | RFC 8725: keys must belong to the issuer | tokens from another issuer, even a real one |
aud | RFC 7519: if the recipient is not in aud, "the JWT MUST be rejected" | a token meant for another service |
exp, nbf | RFC 7519: exp is the time "on or after which the JWT MUST NOT be accepted" | old and not-yet-valid tokens |
| revocation | not in RFC 7519; this example checks a jti deny list | a token revoked before exp (see below) |
Then comes the line the whole site rests on. verify returns valid: True and a note, never "allowed".
Then, separately: may this broker read this quote?#
The quote service turns the validated claims into a subject and asks the policy decision point about one action on one record. The snippet demonstrates that the same valid token gets different answers for different records. It does not demonstrate the rule's design, which lives on Authorization.
import services
import tokens
from clock import START_EPOCH_S as NOW
platform = services.Platform(NOW)
tok = tokens.issue_for("u-broker-n1", aud=tokens.API_AUD, now=NOW)
for record_id in ["Q-5531", "Q-6620"]:
r = platform.read_quote(tok, record_id, "req-" + record_id)
d = r["decision"]
print(record_id, "token valid:", r["gateway"]["valid"], "| status", r["status"], d["rule"], "|", d["reason"])
Q-5531 token valid: True | status 200 R-AZ-03 | broker of tenant brk-north on its own quote
Q-6620 token valid: True | status 404 R-AZ-03 | record belongs to another tenant: not found (existence not revealed)
Same token, same scope quotes.read, two answers. The scope says the broker may read quotes in general; it never says which quote. The tenant on the record decides, under authorization policy authz-2026.11.1. The broker sees a quote, Q-5531; the insurer works the same record as submission SUB-1004, one to one, and the decision is made on the record both ids point to; this site's own case UW-A02 asks for SUB-1004 with the other tenant's valid token and also gets 404.
Diagram: Two machines in a row · is this token genuine and for me, then may this subject do this to this record
Read left to right. The first lane authenticates the token in a fixed order: format, algorithm allowlist, known key, signature; only then issuer, audience, time and revocation. Any failure is 401 and no claim is trusted. The second lane is a different question asked in the service that owns the record: the policy decision point reads the record's tenant and answers 200 for Q-5531 and 404 for Q-6620, with the same valid token.
- Authenticate the token
- format, alg allowlist, known kid: Three base64url parts with JSON header and payload; the algorithm must be on the verifier's own list; the key id must be in the verifier's own key set.
- signature: Recompute the signature over header.payload with the named key. Until it matches, every claim is attacker-written.
- iss, aud, exp, nbf, revocation: The issuer must be the expected one, this service must be in the audience, the time must be inside nbf to exp, and the jti must not be revoked (where checked).
- Decide on the record
- subject from validated claims: The service builds the subject from claims it just validated, plus directory data. Request parameters never set identity.
- PDP: quote.read on this record: The policy decision point compares the subject's tenant with the record's tenant. A scope names an action family, never a record.
Read the diagram as two machines in a row. The first answers "who is calling, and is this token for me?", and it fails closed: any failed check is 401. The second answers "may this subject do this action to this record, now?" and lives in the service that owns the record.
The token lab#
The lab generates a demo token in your browser with the same rules. Edit the issuer, audience, expiry, scope, algorithm or signature and watch which check fails first; then pick an action and see the authorization decision, separately.
The same cases, run by examples/uw-auth/run_cases.py (all 24 of this site's own cases matched their expected blocks on 2026-11-18):
| Case | What was changed | First failed check | Result |
|---|---|---|---|
UW-A07 tampered payload | uw.decide added to scope, old signature kept | signature | invalid; claims not returned, later checks skipped |
UW-A08 alg none | header alg: none, empty signature | alg | invalid; kid and signature not even tried |
UW-A05 wrong audience | token issued for https://assessment-svc.internal.example, sent to the quote API | aud | invalid (signature was fine) |
UW-A06 expired | checked at 901 s after issue (life 900 s) | exp | invalid; at 899 s it was valid |
| key rotation | signed with demo-2026b, verifier knows only demo-2026a | kid | invalid until the verifier's key set includes the new key |
UW-A16 revoked | jti on the deny list, 60 s after issue | revocation | invalid only for verifiers that check the list |
Three failures worth recognising#
The edited token. UW-A07 is the support engineer's experiment. After the signature fails, verify marks iss, aud, exp and the rest as "skipped: claims are not trusted before the signature verifies" and returns no claims. That is the safe habit: code that reads scope from an unverified token, even "only for logging", eventually makes a decision on it.
The token that chose its own algorithm. UW-A08 sends "alg": "none", which RFC 7519 calls an Unsecured JWT. A verifier that reads alg from the token and obeys it accepts a token with no signature. The same mistake has a quieter form, key confusion: a verifier that expects RS256 with a public key, but lets the token say HS256, may end up using the public key as an HMAC secret. Guideline (OWASP JWT Cheat Sheet): "hardcode the accepted algorithms and do not mix public-key digital signatures algorithms and MAC algorithms". Product (PyJWT, as documented on 2026-11-18): "Do not compute the algorithms parameter based on the alg from the token itself."
The right token at the wrong door. UW-A05 is a genuine token, correctly signed, meant for the assessment service. Without the audience check the quote API would accept it, and any service that receives tokens could replay them against every other service of the same issuer. Standard (RFC 8725 §3.9): when one issuer serves several relying parties, "the JWT MUST contain an "aud" (audience) claim" and it must be validated. The same rule keeps an ID token out of an API: its audience is the client application, not the API.
Production pitfall. "We validate the JWT" often means "we check the signature". Ask for the list. Ifaudandissare not on it, any token from your identity provider for any application opens your API.
Keys, key sets and rotation#
The signature is only as good as the verifier's choice of key. With asymmetric algorithms the identity provider signs with a private key and publishes the public keys. Standard (RFC 7517, read 2026-11-18): a JSON Web Key is "A JSON object that represents a cryptographic key", and a JWKS (JWK Set) is "A JSON object that represents a set of JWKs" whose keys member is an array. A tiny example: {"keys": [{"kty": "EC", "kid": "2026a", ...}, {"kty": "EC", "kid": "2026b", ...}]} at the URL that OpenID Connect discovery lists as jwks_uri.
Rotation is an overlap, not a switch. The issuer publishes the next key first; verifiers refresh their key set; then the issuer starts signing with the next key; much later the old key is removed. The example's rotation case shows why the order matters: a token signed with demo-2026b fails at kid for a verifier that still knows only demo-2026a. RFC 7517 asks for distinct kid values within a set. Product (PyJWT): PyJWKClient "fetches and manages JSON Web Key Sets (JWKS) from a remote endpoint" and refetches when a kid is missing.
Algorithm names move too. SURPRISING (RFC 9864, October 2025, read 2026-11-18): it updates RFC 7518 and sets the JOSE identifier EdDSA to "Deprecated", replaced by the fully specified Ed25519 and Ed448; RS256 and PS256 are unchanged. An allowlist written today should name Ed25519, not EdDSA, for new deployments.
Security note. The demo's HMAC keys are shared strings published in demo_keys.py, which is exactly what production must never do. RFC 7518 requires an HMAC key at least as long as the hash output, OWASP asks for at least 160 bits of entropy and never a password, and with a shared key every verifier can also mint tokens. That is why real access tokens use asymmetric keys: resource servers hold only public keys.
Opaque tokens, introspection and the revocation window#
A JWT is self-contained: the API decides without calling anyone. That is fast, and it has a price. Revoke the broker's token at the issuer at 09:01 and an API that checks only signature and exp keeps accepting it until 09:15.
The other design is an opaque token: a random handle that carries no readable claims, which the resource server checks by asking the issuer. Asking is introspection. Standard (RFC 7662, read 2026-11-18): the request carries token; the response member active is required; an inactive, revoked or unknown token gets "active": false and nothing else; the endpoint "MUST also require some form of authorization", so it cannot be used to scan for tokens.
UW-A16 runs both designs on the same token, 60 seconds after issue, after it was revoked. Real output from the scratch copy:
opaque handle: opq-856456c80ed2be33a52a8227
introspect before revoke: {"active": true, "token_type": "Bearer", "scope": "quotes.read quotes.submit", "client_id": "svc-portal-bff", "sub": "u-broker-s1", "aud": "https://api.uw.insurer.example", "iss": "https://idp.insurer.example", "exp": 1794993300, "iat": 1794992400, "nbf": 1794992400, "jti": "jti-c3712785fba8"}
self-contained, no deny list, valid: True
self-contained, deny list, first_failed: revocation
introspect after revoke: {"active": false}
Token revocation is the issuer marking a token as no longer usable before it expires. Standard (RFC 7009): the client POSTs the token with an optional token_type_hint; revoking a refresh token "SHOULD also invalidate all access tokens based on the same authorization grant", where the server supports that. But revocation only reaches resource servers that ask. Introspection responses "MAY be cached" and "MUST NOT be cached beyond" exp, so caching widens the window again.
Diagram: The revocation window · one revoked token, three resource servers
Time runs down the page. The identity provider has revoked the broker's token 60 seconds after issue (UW-A16), and the same token is presented three times. A resource server that checks only signature and expiry accepts it until exp. One that received the revoked jti on a deny list refuses it with 401. One that holds an opaque handle asks the identity provider and hears active false. Revocation reaches only the servers that ask.
- Caller with the revoked token to Quote API: signature + exp: Bearer token at iat+60. The revoked token arrives at a server that never asks the issuer.
- Quote API: signature + exp to Caller with the revoked token: 200: accepted until exp. Nothing told this server about the revocation, so the token works until exp, 900 s after issue.
- Identity provider to Quote API: with deny list: deny list: jti revoked. The issuer distributes the revoked jti; the server must receive it within the access-removal time.
- Caller with the revoked token to Quote API: with deny list: same token. The same self-contained token, at the same moment.
- Quote API: with deny list to Caller with the revoked token: 401: revocation check. The deny-list check fails, so the token is invalid (RFC 6750 invalid_token covers revoked tokens).
- Caller with the revoked token to Quote API: opaque + introspection: opaque handle. An opaque token carries no readable claims.
- Quote API: opaque + introspection to Identity provider: introspect. RFC 7662 request with the token; the endpoint itself requires authorization.
- Identity provider to Quote API: opaque + introspection: active: false. An inactive token gets only active false, with no reason.
- Quote API: opaque + introspection to Caller with the revoked token: 401. The resource server refuses the inactive token.
The three token kinds side by side:
| Access token | ID token | Refresh token | |
|---|---|---|---|
| Purpose | call an API | tell the client who signed in | get new access tokens |
| Audience | the resource (https://api.uw.insurer.example) | the client (svc-portal-bff) | the issuer only (RFC 6749: "intended for use only with authorization servers") |
| Who reads it | the resource server | the client | the authorization server |
| Lifetime in the example | 900 s (illustrative) | 300 s (illustrative) | kept by the BFF; not modelled |
| If stolen | usable until exp | should be refused by APIs (wrong audience) | new access tokens until revoked or rotated |
Standard (RFC 9700, read 2026-11-18): "Refresh tokens for public clients MUST be sender-constrained or use refresh token rotation", and with rotation the authorization server issues a new refresh token on every refresh and must detect reuse of an old one.
Bearer or proof of possession#
A bearer token works for whoever holds it. A proof-of-possession token is bound to a key the legitimate client holds, so a copied token alone is useless: the caller must also prove it holds the key on each request. Two standards do this. RFC 8705 binds the token to the client's TLS certificate: the token carries a cnf claim with x5t#S256, and the resource server "MUST verify that the certificate matches". RFC 9449 (DPoP) binds it at the application level: the client sends a DPoP header with a fresh signed proof per request (htm, htu, iat, jti, ath), and the token is bound through cnf.jkt. RFC 9449 says "a primary use case of DPoP is for public clients". RFC 9700 says authorization and resource servers "SHOULD use mechanisms for sender-constraining access tokens".
This site's recommendation: for the broker portal, the BFF already keeps tokens off the browser, so short-lived bearer tokens between the BFF and the API are the simplest credible design. Sender-constrain when a token travels somewhere it could be copied and replayed: a public client, a mobile app, a token that crosses an organization's boundary.
Choosing a token design#
| Need | Simplest credible choice | Grow when | Alternative |
|---|---|---|---|
| One API, one issuer | JWT access tokens, 5 to 15 minutes, asymmetric signatures, full checks | logout must take effect within seconds | opaque + introspection for that API |
| Immediate revocation | opaque tokens + introspection, with a short cache | introspection load or latency hurts | JWT + deny list keyed on jti |
| Many audiences | one token per audience (token exchange, next page) | delegation chains appear | never one token for every service |
| Token copied from clients | DPoP (public clients) or mTLS-bound (workloads) | shorter lifetimes as a stop-gap |
The trade underneath every row is the same: the more a resource server decides alone, the faster it is and the longer a bad token lives.
In real libraries (these ran)#
Two framework demos in examples/frameworks/ sign real tokens at run time and validate them with maintained libraries. Library (PyJWT 2.15.1 with FastAPI 0.165.0, ran 2026-11-18): a dependency calls jwt.decode(..., algorithms=["ES256"], audience=..., issuer=..., options={"require": ["exp", "iss", "aud", "sub"]}); the run (fastapi-jwt/run.sh, 19 passed) answered 401 for no token, expired, wrong audience, wrong issuer, an RS256 token, alg: none and another key's signature, 403 for a missing scope, and kept the object-level rule in the endpoint (404 for another tenant's quote). Library (Spring Security 7.1.2 with Spring Boot 4.1.2, ran 2026-11-18): mvn -q test, 17 tests, 0 failures, with a NimbusJwtDecoder built from a local public key.
The Spring run carries two lessons worth copying into any review. First, Spring does not check aud by default. The documentation says the resource server "will default to verifying the iss claim as well as the exp and nbf timestamp claims"; the demo adds a JwtClaimValidator on aud next to JwtValidators.createDefaultWithIssuer(...), and the wrong-audience test then gets 401. Second, the jwt() test helper "create[s] a mock Jwt" and puts it straight into the security context: the decoder never runs. The run proves it: a jwt() request with the wrong audience got 200. Use jwt() for authorization tests, and keep tests with real signed tokens for validation. Spring's default clock skew is 60 seconds, so an "expired" test token must be older than that.
What this is not. This page does not explain how the token was obtained (authorization code, client credentials) or how one service gets a narrower token for another (token exchange). Both are on OAuth, OIDC and federation. Tokens that carry an agent's delegated authority are on Agents.
In a coding agent. A coding agent in CI gets no stored cloud key. The CI system issues a short-lived OIDC token whose audience is the cloud provider, and the cloud exchanges it for temporary credentials. Every check above applies: issuer, audience, expiry, and asubthat names the repository and branch (GitHub's documented format, for examplerepo:OWNER@OWNER-ID/REPO@REPO-ID:ref:refs/heads/BRANCHfor repositories created after 15 July 2026), so the cloud's trust policy can accept exactly one repository and branch. The details are on Coding agents.
Security notes#
- Never decide on claims from an unverified token; decode-without-verify is for display only.
- Configure the algorithm list, the issuer and the audience; never take any of them from the token.
- Treat every token as readable; no personal data a broker should not see goes in claims.
- Tokens stay out of URLs and logs; RFC 6750 says bearer tokens "SHOULD NOT be passed in page URLs".
- Short access-token lifetimes are your revocation plan unless you introspect.
Monday checklist#
- Your verifier rejects
alg: none, an unexpected algorithm, an unknownkid, a wrongiss, a wrongaud, and an expired token: one negative test each. - Audience validation is on in every resource server (check Spring and any framework whose defaults you have not read).
- The key set is fetched from the issuer's
jwks_uri, refreshed on unknownkid, and a rotation has been rehearsed. - Access-token lifetime written down, with the revocation window it implies.
- Tests that use framework helpers like
jwt()are paired with tests that send real signed tokens. - A test where a valid token asks for another tenant's record and gets 404.
Exercises#
Exercise 1. A colleague proposes reading tenant from the token in an API gateway log line "before validation, for debugging". What is the risk?
AnswerAttacker-written data in a trusted place
Before the signature verifies, every claim is attacker-written. Logging it plants forged tenants in the audit trail, and code that "only logs" a value tends to start deciding on it. Log claims only after validation, and never the token itself.
Exercise 2. The quote API validates signature, iss and exp, but not aud. Which case on this page does it fail, and what can an attacker do with that?
AnswerUW-A05: tokens replay across services
It accepts UW-A05: a token meant for the assessment service. Any service that receives tokens from the same issuer, or anyone who obtains such a token, can call the quote API with it.
Exercise 3. Logout must cut off a broker within one minute. The tokens are self-contained JWTs that live 15 minutes. Name two designs that meet the requirement.
AnswerIntrospection, or a deny list, or one-minute tokens
Opaque tokens with introspection cached under a minute; or a jti deny list that every resource server reads; or access tokens of about a minute refreshed through the BFF. Keeping tokens in a BFF with a server session also lets logout stop new calls immediately, though tokens already sent to other services still live to exp.
Advanced perspective#
The JWT access token profile and token confusionRFC 9068 types the token so validators cannot mix kinds
Token format (RFC 9068, read 2026-11-18): "JWT access tokens MUST include this media type in the "typ" header parameter": at+jwt. Required claims are iss, exp, aud, sub, client_id, iat, jti; the resource server rejects a token whose typ is not at+jwt and "MUST reject any JWT in which the value of "alg" is "none"". The point is explicit typing: RFC 8725 says "Explicit typing is RECOMMENDED for new uses of JWTs" and that validation rules for different JWT kinds "MUST be written such that they are mutually exclusive". Without it, an ID token, a logout token and an access token from the same issuer look alike to a careless validator. The example's demo tokens use typ: JWT and so do not follow RFC 9068; a production issuer of JWT access tokens should.
Deny lists done rightKey on jti, bound the list by exp, distribute fast
A deny list turns a self-contained token back into a looked-up one, so make the lookup cheap. Key it on jti (or on subject plus issued-before time for "revoke everything for this broker"), never on the raw token: OWASP warns that using the token or its SHA-256 hash as the key is unsafe because of JWT malleability, and points to Token Status Lists as an alternative. Entries expire at the token's exp, so the list stays small. Distribution is the real cost: every resource server must see the entry within your access-removal time, which means a push channel or a short poll. If you need this everywhere, introspection may be simpler.
Rotating signing keys without an outagePublish, wait, sign, wait, remove
The safe sequence: (1) publish the new public key in the JWKS next to the old one; (2) wait at least the longest key-set cache time of any verifier; (3) start signing with the new key; (4) wait at least the longest token lifetime; (5) remove the old key. Steps 2 and 4 are the ones skipped under pressure, and each causes a different outage: verifiers rejecting new tokens at kid, or rejecting old tokens still in flight. For an emergency rotation after a key leak, skip step 4 on purpose: removing the old key invalidates every token it signed, which is the goal. Rehearse both. Operations depth is on Operations.
What belongs in claimsStable facts yes, fine-grained permissions no
Claims are snapshots taken at issue time. Put in what is stable for the token's life and needed by many services: subject, tenant or business unit, coarse scopes, authentication strength (acr, auth_time). Keep out what changes or is large: per-record permissions, assignments, group lists that grow. Product (Microsoft Entra ID, as documented on 2026-11-18): above 200 groups a JWT carries no groups claim and an overage claim points to Microsoft Graph instead, and Microsoft advises keeping "finer-grained resource permissions in your application's authorization data". The example follows that: the assignment of SUB-1004 to u-uw-w1 lives in the directory, read by the policy decision point at decision time.
In one breath#
A JWT is a signed, readable statement: anyone can decode it, nobody can change it unnoticed. A resource server checks format, an algorithm allowlist, the key, the signature, then issuer, audience and time, and trusts no claim before the signature. Revocation reaches only servers that ask, so lifetimes, introspection and deny lists are a trade between speed and how long a bad token lives. And then the service still decides on the record: a valid token is not a permission.
The quote API can now tell a genuine broker token from a forged, expired or misdirected one. What it has taken on faith is how that token came to exist: who logged in, which client asked, and how one service can get a narrower token for the next hop without forwarding the broker's. OAuth, OIDC and federation follows the token back to its origin.