Jan Mikoláš
Glossary
JWT
A JWT is easy to decode, but that does not make it trustworthy. Its cryptographic protection and expected claims must be validated before making an access decision.
Short definition
A compact envelope for verifiable claims.
A conventional signed JWT, known as a JWS, has a header, payload, and signature separated by dots. The header and payload are Base64URL-encoded, not encrypted: they can be read, but an application must not trust them until it has successfully verified the signature.
A JWT can also be encrypted as a JWE, which protects the confidentiality of its contents. Signing and encryption are distinct properties. JWT is not synonymous with OAuth 2.0, an access token, or a server-side session; it is a standard format that can be used in different protocols.
Use cases
When a JWT carries identity or permissions
A token should have a specific issuer, recipient, and narrowly defined, short-lived purpose.
- an access token for a protected backend API
- an ID token issued by an OpenID Connect provider
- short-lived tokens between services with a clear audience
- passing verifiable claims without a database query on every request
- rotating public verification keys through JWKS
Practical example
An API validates an access token for order imports
A B2B client sends an access token to the import API. From trusted configuration, the API knows the issuer and its own audience. It selects a key from the relevant JWKS by kid and verifies the explicitly allowed algorithm, signature, issuer, audience, and expiration.
Only then does it allow the import scope and verify that the client is working with the specified tenant. The token is not parsed by hand for cryptographic operations, and the log contains only a safe correlation value, not the complete JWT.
How it works
From issuing a token to API authorization
At first, the token remains untrusted input. Authorization comes only after validation.
- Issuance A trusted issuer creates claims with a purpose and limited lifetime, then signs the token as a JWS or encrypts it as a JWE where needed.
- Transmission The client passes the token to the protected API as a credential; it must not appear in URLs, logs, or error messages.
- Key selection Based on a pre-trusted issuer and the kid, the API selects the corresponding key from a configured set or JWKS.
- Verification It uses an explicitly allowed algorithm and verifies the token protection, iss, aud, exp, and, where applicable, nbf and the expected token type.
- Decision Only after validation does it check the scope or application permissions for the specific tenant and data.
Key concepts
The parts of a token and their limits
Cryptographic validation is essential, but it does not replace business authorization.
Claims
iss is the issuer, sub the subject, aud the recipient, exp the expiration time, nbf the time before which it is invalid, iat the issue time, and jti an identifier. The application must define which claims it expects and what they mean.
Decode and verify
Decode only unpacks the structure. Verify checks the signature or encryption and the token context. A decoded payload must not control access.
Algorithm and key
An algorithm named in an untrusted header is not an instruction to the application: the verifier uses an allowlist and the correct key type. It must not accept alg none or an arbitrary key URL.
JWKS and rotation
JWKS publishes a set of public keys; the application trusts them only through a preconfigured issuer or verified Discovery. A new key is made available before tokens are signed with it, while the previous one remains available for the lifetime of older tokens.
Benefits and limitations
Portable claims at the cost of a clear validation policy.
Benefits
- a compact, standardised representation of claims
- verification with a public key without sharing the private key
- natural interoperability between separate API services
- gradual key rotation through JWKS
Risks
- a JWS payload is not secret and must not contain passwords or sensitive data
- a long expiration increases the impact of a leak and complicates revocation
- roles inside a token can become stale
- checking only the signature without iss and aud can allow a token intended elsewhere
Scope
Choose according to the security and operational model.
A short-lived JWT is useful when multiple services need to verify trusted claims without a shared session database. It still requires strict validation, key management, and a plan for invalidating access. A short expiration reduces the impact of a leak, but does not provide immediate revocation.
A conventional server-side session may be simpler and easier to control for a web application. Frequently changing data and every permission do not belong in a token. For a sensitive action, an application may require a current state check independently of the token contents.
What to consider
Treat tokens as credentials.
Cryptography should be entrusted to a proven library rather than handwritten code.
- an allowlist of expected algorithms and keys from a trusted issuer
- validation of the signature, iss, aud, exp, and other required claims
- a short lifetime, key rotation, and a considered revocation plan
- no secrets or unnecessary personal data in a signed payload
- no logging of the token, URL parameters, or the entire identity payload
Common questions
What actually needs to be verified
Is a JWT encrypted?
Not automatically. A conventional JWS is signed but readable. JWE or another appropriate safeguard provides confidentiality.
Is decoding the JWT payload enough?
No. Decode is not verify. Until its protection and claims have been verified, the payload is untrusted input.
What should an API verify?
The expected format, an explicitly allowed algorithm, cryptographic protection, issuer, audience, validity, and the claims required for that token type.
Is a JWT suitable as a permanent session?
Not automatically. A long lifetime increases the impact of a leak and complicates revocation. The right choice depends on the application model.
How I design API boundaries in practice
I evaluate tokens by their purpose, expiration, and actual permissions.
For integration APIs, I address secure authentication, limited access, validation, and traceability of operational errors.