How JWT Tokens Work

JWT tokens are everywhere in modern APIs, but they are often used before they are understood. Teams paste a bearer token into a request header, inspect a payload in a decoder, or wire middleware around `exp` and `aud` claims without stepping back to ask what problem the token is actually solving. That gap creates security mistakes. A JWT is not automatically safe because it is signed, and it is not automatically dangerous because it is readable. It is a compact, structured container for claims that only becomes trustworthy after the receiving system verifies the token correctly.

This article walks through that structure from beginner to practical engineering level. It explains how the header, payload, and signature work together, how authentication differs from authorization, when access tokens and refresh tokens should be used, and why algorithm choices like HS256, RS256, and ES256 change operational tradeoffs. It also links the token workflow to adjacent tools such as the JWT Decoder, JSON Formatter, Base64 Encoder/Decoder, and Unix Timestamp Converter so you can debug real systems without guessing.

JWT in one sentence

A JSON Web Token is a compact string made of three dot-separated parts that represents claims and a cryptographic signature. In practice, a system issues the token after authentication, then clients present it as a bearer token to APIs. The receiving API checks the signature, validates metadata such as issuer and expiration, and uses the approved claims to make authorization decisions. That is why a JWT belongs to an authentication flow but does not replace the whole identity system around it.

If you only remember one operational truth, remember this: decoding is not verification. The JWT Decoder is useful because it makes the token readable, but readable does not mean trusted. That distinction is the source of many production bugs and many avoidable security incidents.

Authentication versus authorization

JWT discussions get messy when teams blur authentication and authorization. Authentication answers the question, “Who is this caller?” Authorization answers the question, “What is this caller allowed to do?” A login system may authenticate a user with a password, magic link, passkey, or third-party identity provider. After that step succeeds, the system may issue a JWT access token so downstream services do not need the original login event every time a request arrives.

Authorization happens after that. An API may look at claims such as `sub`, `scope`, `role`, `tenant_id`, or `permissions` and decide whether the token holder can read a record, modify a resource, or call an administrative endpoint. The token helps carry those facts, but the policy logic still lives in the API or gateway. That is why strong systems keep claims small and purposeful instead of stuffing entire user profiles into the payload.

JWT structure: header, payload, signature

A JWT has three parts separated by periods: the header, the payload, and the signature. The header usually contains the token type and the signing algorithm. The payload contains claims, which may include standard claims like `iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, and `jti`, plus application-specific custom claims. The signature is created from the encoded header and payload using a secret key or a private key, depending on the algorithm.

header.payload.signature

The header and payload are Base64URL-encoded JSON. That matters because engineers sometimes confuse encoding with encryption. A JWT payload is not secret just because it looks unreadable at first glance. If you want to inspect it manually, the Base64 Encoder/Decoder and JSON Formatter are the simplest way to see why the data is only encoded. If a token must carry confidential data, the safer design is usually to avoid placing that data in the token at all.

Standard claims and custom claims

Standard claims exist so systems can agree on a shared vocabulary. `iss` names the issuer. `sub` identifies the subject. `aud` defines the intended audience. `exp` sets the expiration time. `nbf` says when the token becomes valid. `iat` records when it was issued. `jti` can serve as a unique token identifier. Those claims are enough for many validation paths, especially when an API must reject stale, early, or misrouted tokens before application code runs.

Custom claims are where teams often overreach. A small custom claim like `tenant_id`, `plan`, or `scope` can be useful. A large custom claim that duplicates a complete user record, UI preferences, billing profile, and nested ACL structure usually creates unnecessary exposure and token bloat. It also complicates debugging when you need to compare a decoded payload with the canonical data in a database or API response. When that happens, use the JSON Compare Tool rather than assuming the token should be the source of truth.

Bearer tokens and real API authentication

Most APIs receive JWTs as bearer tokens in the `Authorization` header:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

The word “bearer” matters because possession is enough to attempt access. If an attacker steals the token from logs, browser storage, a compromised extension, or an unprotected network hop, they can present it unless additional protections exist. That is why bearer tokens should be short-lived, transmitted only over HTTPS, and stored carefully. The most common operational failure is treating a bearer token like a harmless debugging string instead of a live credential.

In a real flow, an identity provider or application backend authenticates the user, issues the token, and returns it to the client. The client stores it, then sends it to APIs. The API verifies the signature, validates the claims, and makes authorization decisions. If the client also holds a refresh token, it can obtain a new access token without forcing the user to log in again. The access token is for API calls. The refresh token is for token renewal. They should not be treated as interchangeable.

Access tokens, refresh tokens, and expiration

An access token should usually be short-lived. Its purpose is to reduce risk if the token is leaked while still allowing the API to work efficiently. A refresh token usually lives longer and is exchanged with the authorization server for a new access token when needed. Because refresh tokens are more durable and can keep a session alive, they typically deserve stricter storage rules and tighter rotation policies.

Expiration values are often represented as Unix timestamps, which is why the Unix Timestamp Converter becomes useful when debugging `exp`, `nbf`, and `iat` claims. A token that “looks fine” in decoded JSON can still fail because the issuing clock is skewed, the client uses the wrong environment, or the API expects seconds while another service logged milliseconds. Time bugs are common in distributed authentication systems because everything appears valid until the systems disagree by just enough.

HS256, RS256, and ES256

HS256 is a symmetric signing algorithm. The same secret is used to create and verify the signature. It is operationally simple, but it requires careful secret distribution because every verifier that can validate the token also effectively depends on the same shared secret. That can be acceptable in smaller, tightly controlled systems, but it becomes riskier as more services are added.

RS256 uses asymmetric cryptography. A private key signs the token, and a public key verifies it. That separation is powerful in multi-service environments because verifiers do not need the signing key. ES256 follows a similar asymmetric model with elliptic curve cryptography and often yields shorter signatures. The main tradeoff is implementation maturity and platform support. Teams should choose the algorithm their identity platform supports well and then focus on secure verification, key rotation, and operational clarity instead of chasing novelty.

Secret keys, public keys, and operational hygiene

JWT security depends less on the token format than on key management discipline. A symmetric secret should not be committed to source control, copied into multiple services casually, or reused across unrelated environments. A private key should be protected with the same seriousness as any signing credential. Public keys should be distributed in a way the API can trust, often through a metadata endpoint or JWKS document in standards-based identity systems.

This is where teams sometimes misuse developer tools. A decoded token can help you inspect `kid`, `alg`, or `iss`, but it will not fix a broken key distribution design. If you suspect a signature mismatch, use the Hash Generator only as a conceptual aid for understanding signatures and digests. Do not invent your own verification shortcuts around production JWTs. Let a proven library verify the token exactly as the algorithm and issuer expect.

OAuth overview without the usual confusion

OAuth is an authorization framework, not a synonym for JWT. Many OAuth and OpenID Connect systems issue JWT access tokens or ID tokens, but OAuth itself is about delegated access and token exchange patterns. In practice, this means a developer can be looking at an OAuth flow and still need to reason separately about whether the specific access token is opaque, JWT-based, or environment-specific. Confusion happens when teams assume all OAuth tokens are JWTs or that all JWTs are part of OAuth.

The practical approach is simple. Treat OAuth as the flow and policy layer. Treat JWT as one possible token format inside that flow. When debugging an OAuth-based API issue, inspect the token structure with the JWT Decoder, verify the payload shape with the JSON Formatter, and confirm redirect or callback encoding details with the URL Encoder/Decoder if the failure is earlier in the authorization process.

Real-world debugging workflow

A useful JWT debugging workflow is staged. First, decode the token to inspect the header and payload. Second, confirm the issuer, audience, expiration, and not-before claims. Third, check the algorithm and key identifier. Fourth, compare the custom claims with what the API actually expects. Fifth, verify whether the token belongs to the right environment, tenant, or application. Sixth, only after those structural checks, move into key-distribution or middleware-level debugging.

In practice, you often move across several tools. Use the JWT Decoder for anatomy, the Unix Timestamp Converter for time fields, the JSON Compare Tool when you need to inspect differences between a working and failing token, and the Regex Tester if log pipelines or security filters are extracting bearer tokens incorrectly. If the token payload includes identifiers that must be traced back to API or SQL systems, the SQL Formatter and JSON cluster become useful context tools instead of disconnected utilities.

Security best practices and common mistakes

The most common JWT mistakes are predictable. Teams trust decoded payloads without verification. They store access tokens in unsafe places. They make tokens live too long. They embed sensitive data directly in the payload. They accept the wrong issuer or audience. They allow algorithms they did not intend to support. They confuse refresh tokens with access tokens. They let logs capture live bearer tokens. These are process failures more often than cryptographic failures.

The best practices are equally predictable. Use proven libraries. Verify signature, issuer, audience, and time-based claims. Keep tokens small. Use short-lived access tokens. Protect refresh tokens carefully. Rotate keys deliberately. Avoid storing unnecessary secrets or personal data in claims. Treat tokens as credentials. Keep your debugging workflow disciplined enough that a readable payload never becomes a substitute for real validation.

FAQ

Related articles

Related tools