JSON Web Tokens: Structure, What Belongs in the Payload and the Difference Between Decoding and Verifying

Reading a JWT reveals recorded claims; accepting those claims requires a separate validation process. This distinction matters because an attacker can create plausible-looking JSON without possessing an issuer’s signing key.

The following explanation covers the common compact JWS representation of a JWT. It has three dot-separated parts: protected header, payload and signature or message authentication code (MAC). The first two are Base64url-encoded JSON, not encrypted. A compact encrypted JWT uses JWE and has five parts. JWT describes a format; not every JWT is an access token.

What the three parts establish

The header identifies the cryptographic algorithm through alg and may contain a key identifier, kid. The payload contains claims about an issuer, subject, audience or authorization context. The third part protects the encoded header and payload against undetected modification and authenticates creation by a holder of the relevant signing or MAC key.

With an asymmetric algorithm, a private key signs and a corresponding public key verifies. With HS256, a shared secret creates and verifies the MAC. Every holder of that secret can also produce valid MACs; verification does not uniquely identify one particular secret holder. A valid result under an arbitrary key is not enough: the application must trust that key for the expected issuer and purpose.

Decoding, validation and authorization

1. Decoding: parse the expected representation and inspect fields as untrusted input.
2. Cryptographic validation: accept only configured algorithms and appropriate trusted keys; verify the actual signature or MAC.
3. Context validation: enforce issuer, audience, token type, required claims and time rules for the applicable profile.
4. Authorization: decide whether the validated subject and permissions permit this operation on this resource.

A decoder can display a fabricated token. Conversely, a token with a correct signature can still have the wrong audience, be expired or lack permission for the requested account. A library call is useful only when its configuration and the application’s remaining checks implement the intended rules.

The application defines an algorithm allowlist; the token’s alg must match it and the permitted key type. An unsigned alg: none token is unacceptable where a signature is required. RS256-to-HS256 confusion is a known failure of vulnerable or misconfigured verification, not an inevitable behavior of every verifier. The public RSA key must never become an HMAC secret.

kid is an untrusted lookup hint. It may select a key from a trusted issuer’s configured key set, including a safely retrieved JWKS. It must not authorize arbitrary token-supplied keys, URLs or file paths. An ID token must not be accepted as an API access token merely because both use JWT.

Claims that fit the actual task

Passwords, private keys and unnecessary personal information do not belong in a readable payload. Even a short identifier can be sensitive. Real tokens therefore need protection in storage, transport, diagnostics and support workflows; demonstration material should contain synthetic data.

Roles, scopes or tenant identifiers are not categorically forbidden. RFC 9068 explicitly accommodates roles and related authorization claims. Their inclusion depends on the receiving service’s needs, disclosure risk and how quickly changes must take effect. A role embedded in an issued token can become stale. Server lookups, short lifetimes or other controls may be necessary; a lookup does not automatically happen in every JWT design.

sub identifies the subject, iss the issuer and aud the intended recipient or recipients. RFC 7519 does not make all registered claims mandatory in every JWT. A concrete protocol profile can require them: the OAuth access-token profile in RFC 9068 imposes additional requirements. Presence alone is insufficient; issuer and audience must be compared with expected values.

Expiry and server-side rules

exp and nbf use NumericDate values in seconds since the Unix epoch, not JavaScript milliseconds. Without clock-skew leeway, acceptance requires now < exp and, when present, now >= nbf. At exactly the expiry instant the token is expired. The server must also require the claims mandated by its profile; a missing exp must not silently bypass a policy requiring expiry.

No exp does not universally mean unlimited validity. Server policy, revocation, account state and key trust can independently prevent acceptance. Deleting a browser copy does not revoke other copies. Possible designs combine short-lived access tokens with revocable refresh tokens, deny lists or introspection. A jti identifier alone does not implement revocation or replay prevention.