JWT Guide

JWT Guide explains how JSON Web Tokens are structured, signed, verified, and used in modern authentication and API workflows. This practical JWT Guide covers headers, payloads, signatures, registered claims, expiration, Base64URL encoding, HMAC algorithms, security limits, common implementation errors, and a reliable testing workflow with Trexmi tools.

A JSON Web Token is a compact string used to transfer claims between systems. JWTs often appear in login sessions, API authorization headers, single sign-on integrations, and service-to-service communication. The token format is standardized, but safe use depends on correct signature verification, claim validation, key management, and expiration handling.

JWT Guide to token structure

A JWT normally contains three dot-separated segments:

header.payload.signature

The first two segments are Base64URL-encoded JSON. The third segment is a cryptographic signature or message authentication code. A decoder can reveal the header and payload without knowing the secret, so sensitive data must never be placed in a token merely because the token looks unreadable.

Header

The header identifies the token type and signing algorithm.

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload

The payload contains claims about the subject and token context.

{
  "sub": "user-42",
  "role": "editor",
  "iat": 1785990000,
  "exp": 1785993600
}

Signature

The signature covers the encoded header and payload. For HS256, the issuer and verifier share one secret. For asymmetric algorithms such as RS256 or ES256, a private key signs and a public key verifies.

JWT Guide to registered claims

Registered claims have standardized names and meanings. They are optional at the format level, but many applications require a specific subset.

• iss identifies the issuer.
• sub identifies the subject.
• aud identifies the intended audience.
• exp defines the expiration time.
• nbf defines when the token becomes valid.
• iat records the issue time.
• jti provides a unique token identifier.

This JWT Guide recommends validating every claim required by the application instead of checking only the signature. A correctly signed token can still be unacceptable if it is expired, issued by the wrong authority, intended for another service, or used before its validity window begins.

JWT Guide to Base64URL encoding

JWT segments use Base64URL rather than standard Base64. Base64URL replaces plus with hyphen and slash with underscore, and padding is commonly omitted. Encoding is reversible and provides no confidentiality.

Use the Base64 Decoder only for general encoding tests. JWT-aware tools are safer because they understand segment boundaries, Base64URL rules, JSON parsing, and token metadata.

Signing algorithms and algorithm selection

HS256, HS384, and HS512

HMAC algorithms use one shared secret. They are simple and efficient, but every verifier that knows the secret can also create valid tokens. Use a strong random secret and keep it out of source code and public logs.

RS256 and ES256

Asymmetric algorithms separate signing and verification. The issuer keeps the private key while services verify with a public key. This model is often preferable when many systems need to verify tokens but should not be able to issue them.

Warning: Never trust the algorithm declared by an unverified token without enforcing an application-side allowlist.

A reliable JWT Guide verification workflow

1. Split the token into exactly three segments.
2. Decode the header and payload using Base64URL rules.
3. Reject malformed JSON or unexpected header fields.
4. Enforce an allowlist of accepted algorithms.
5. Select the trusted secret or public key from server-side configuration.
6. Verify the signature before trusting claims.
7. Validate expiration, not-before, issuer, audience, and subject requirements.
8. Apply clock-skew tolerance conservatively.
9. Reject tokens that fail any required validation step.

Use JWT Decoder to inspect token structure and claims. Use JWT Generator to create controlled HS256 test tokens. Inspect complex payload JSON with JSON Viewer.

JWTs in HTTP authorization

APIs commonly receive a JWT in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

The server must extract the token carefully, verify it, validate its claims, and map the subject or permissions to current application state. A role stored in a long-lived token may become stale after permissions change, so critical authorization decisions may require a database or policy check.

Expiration and refresh strategies

Short-lived access tokens reduce the damage caused by theft. Refresh tokens can obtain new access tokens, but they require stronger storage, rotation, revocation, and reuse detection. Avoid issuing access tokens with very long expiration periods only to reduce login frequency.

This JWT Guide recommends treating access and refresh tokens as separate credentials with different lifetimes and storage rules. Browser applications should also consider cross-site scripting, cross-site request forgery, cookie flags, and token exposure in URLs or logs.

Common JWT implementation errors

Decoding without verifying

Displaying claims is not the same as authenticating them. Anyone can construct a token with a chosen payload.

Accepting any algorithm

Allowing the token header to choose the verification method can create algorithm-confusion vulnerabilities.

Skipping issuer or audience checks

A token created for one application may be replayed against another service if audience and issuer are ignored.

Embedding confidential data

The payload is readable by anyone who receives the token. Store identifiers and necessary claims, not passwords, private data, or secrets.

Weak HMAC secrets

Short or predictable secrets can be guessed offline from a captured token. Use high-entropy random values and rotate them deliberately.

No revocation strategy

Signed tokens remain valid until expiration unless the system tracks revocation, token versions, session state, or key rotation.

JWT versus server-side sessions

JWTs are useful when claims must travel across service boundaries and independent systems need to verify them. Traditional sessions are often simpler when one application controls authentication and can store session state centrally. JWT is not automatically faster, safer, or more scalable; the correct choice depends on revocation, architecture, trust boundaries, and operational requirements.

JWT Guide security best practices

• Always verify signatures before trusting claims.
• Enforce a strict algorithm allowlist.
• Validate issuer, audience, expiration, and not-before claims.
• Use short-lived access tokens.
• Protect signing secrets and private keys.
• Rotate keys with a documented transition strategy.
• Never include confidential data in the payload.
• Avoid placing tokens in URLs, analytics events, or application logs.
• Use HTTPS for every token exchange.
• Plan revocation and incident response before deployment.

Authoritative JWT references

Review RFC 7519 for the JWT format and registered claims. The JWT Best Current Practices document explains common security failures and recommended validation rules.

JWT Guide summary

This JWT Guide concludes that a token is trustworthy only after its signature and required claims have been validated against application-controlled rules. Decode tokens for inspection, but never confuse readable claims with verified identity. Keep access tokens short-lived, protect keys, restrict algorithms, validate issuer and audience, and choose JWT only when its distributed verification model fits the architecture.