JSON Web Token (JWT): How JWT Works and What Its JSON Payload Really Means

A JSON Web Token (JWT) is a compact, URL-safe format used to represent claims that can be transferred between parties. A JWT can contain information such as:

• User ID
• Username
• Role
• Permissions
• Token issuer
• Expiration time
• Token creation time
• Other application-specific claims

For example, a decoded JWT payload might look like:

1{
2  "sub": "12345",
3  "name": "Alice",
4  "role": "admin",
5  "iat": 1793347200,
6  "exp": 1793350800
7}

This is ordinary JSON data. The important part is that the JSON payload is then encoded and combined with a header and cryptographic signature to create the final JWT.

JWT stands for JSON Web Token. The name describes its basic design:

JWT is standardized as an open Internet specification and is commonly used across different programming languages and platforms.

A typical JWT has three parts separated by periods:

1Header.Payload.Signature

For example:

1eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
2.
3eyJzdWIiOiIxMjM0NSIsInJvbGUiOiJhZG1pbiJ9
4.
5SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Understanding these three components is the key to understanding JWT.

The first section is the header. A decoded JWT header might look like:

1{
2  "alg": "HS256",
3  "typ": "JWT"
4}

The two common properties here are:

"alg"

alg specifies the cryptographic algorithm used to create the signature. For example, HS256 means the token uses the HMAC SHA-256 algorithm. Other algorithms include asymmetric signing algorithms such as RS256 or ES256.

"typ"

typ indicates the type of token. For a JWT, this is commonly "JWT". The header is then Base64URL encoded.

The second section is the JWT payload. This is where the token's claims are stored.

1{
2  "sub": "12345",
3  "name": "Alice",
4  "role": "admin",
5  "iat": 1793347200,
6  "exp": 1793350800
7}

The payload is JSON, but it is important to understand one major security concept:

A JWT payload is encoded, not automatically encrypted.

The properties inside the payload are called claims. A claim is simply a piece of information asserted by the token. JWT claims are commonly divided into three categories:

Registered JWT Claims

Some important registered claims include:

1{
2  "iss": "https://example.com"
3}

1{
2  "sub": "user_123"
3}

1{
2  "aud": "my-api"
3}

1{
2  "exp": 1793350800
3}

1{
2  "iat": 1793347200
3}

1{
2  "nbf": 1793347200
3}

Custom JWT Claims

Applications can also include custom claims. For example:

1{
2  "sub": "12345",
3  "role": "admin",
4  "department": "engineering"
5}

Here sub is a standard registered claim, while role and department can be application-specific claims. Avoid putting unnecessary information into tokens because JWTs are commonly sent with API requests and can increase request size.

The third part is the signature. Conceptually, a signed JWT is created by taking the Base64URL-encoded header, a period, and the Base64URL-encoded payload, and signing them with the selected cryptographic algorithm and key:

1HMACSHA256(
2  base64UrlEncode(header) + "." +
3  base64UrlEncode(payload),
4  secret
5)

The resulting signature is appended to the token. It allows the receiving application to verify that the token has not been modified.

This is one of the most common JWT misconceptions. No, a normal signed JWT is not encrypted. Consider this payload:

1{
2  "userId": "123",
3  "role": "admin"
4}
5
6// Base64URL encoded (NOT encrypted):
7eyJ1c2VySWQiOiIxMjMiLCJyb2xlIjoiYWRtaW4ifQ

After encoding it may look like unreadable text, but Base64URL encoding is not encryption. Anyone who has the token can decode the payload.

The signature provides integrity and authenticity verification, not confidentiality.

If sensitive information must be encrypted, a different mechanism such as an encrypted token format may be appropriate.

A typical JWT authentication flow looks like this:

1User
2  ↓
3Login
4  ↓
5Authentication Server
6  ↓
7JWT issued
8  ↓
9Client stores token
10  ↓
11Client sends JWT with API request
12  ↓
13Server verifies token
14  ↓
15Request accepted

1POST /login
2
3{
4  "email": "alice@example.com",
5  "password": "example-password"
6}

1{
2  "sub": "12345",
3  "role": "user",
4  "iat": 1793347200,
5  "exp": 1793350800
6}

1Authorization: Bearer eyJhbGciOi...

1{
2  "role": "admin"
3}

JWT itself does not magically authenticate a user. JWT is a token format. An application decides how that token is issued, transported, stored, validated, expired, revoked, and used for authorization.

You can use JWT as part of an authentication system, but JWT itself is not a complete authentication solution.

JWT uses Base64URL encoding for its header and payload. Each JSON object is encoded into a compact string, and the token is assembled as:

1encodedHeader.encodedPayload.signature

That's why a JWT looks like a long string rather than readable JSON. Base64URL provides a compact, URL-safe representation.

Yes. The header and payload of a normal JWT can be decoded because they are encoded rather than encrypted, for example by a JWT debugging or development tool. However:

Decoding a JWT is not the same as verifying it.

A decoded token may show you what claims it contains, but only proper signature verification can establish whether the token was signed by a trusted issuer and has not been modified.

The complete JWT is conceptually HEADER.PAYLOAD.SIGNATURE. Consider this simplified setup.

1{
2  "alg": "HS256",
3  "typ": "JWT"
4}

1{
2  "sub": "12345",
3  "name": "Alice",
4  "role": "admin",
5  "iat": 1793347200,
6  "exp": 1793350800
7}

The signature is generated from the encoded header and payload. This gives the server a compact token that carries both identity-related claims and a mechanism for detecting modification.

JWT authentication is often compared with traditional server-side sessions.

1Login
2  ↓
3Server creates session
4  ↓
5Session stored server-side
6  ↓
7Client receives session identifier
8  ↓
9Client sends identifier
10  ↓
11Server looks up session

1Login
2  ↓
3Server creates signed JWT
4  ↓
5Client receives token
6  ↓
7Client sends token
8  ↓
9Server verifies token

Neither approach is automatically better in every situation. Session-based authentication can make server-side session management and revocation straightforward. JWTs can be useful when tokens need to be consumed by multiple services or systems and when stateless verification is desirable. The right choice depends on the architecture.

JWT is powerful, but implementation details matter.

1{
2  "sub": "12345",
3  "exp": 1793350800
4}

1{
2  "username": "alice",
3  "password": "secret123"
4}

Depending on your architecture, validation may include:

• Signature
• Issuer ("iss")
• Audience ("aud")
• Expiration ("exp")
• Not-before ("nbf")
• Expected algorithm

Many authentication systems use two different token concepts. An access token is used to access protected resources and is often short-lived. A refresh token is used to obtain a new access token after the current one expires.

1Login
2  ↓
3Access Token + Refresh Token
4  ↓
5API requests use Access Token
6  ↓
7Access Token expires
8  ↓
9Refresh Token used
10  ↓
11New Access Token

The exact implementation and storage strategy should be designed carefully because refresh tokens are highly sensitive credentials.

An API key is typically a relatively simple secret identifier used to authenticate an application or client. A JWT can contain structured claims and can be cryptographically signed.

1API Key
2──────────────
3abc123xyz
4
5JWT
6──────────────
7header.payload.signature

JWTs are particularly useful when the token needs to carry structured claims such as identity, audience, issuer, and expiration.

The name JSON Web Token is not accidental. JSON is used primarily in the header and payload.

1JWT
2│
3├── Header → JSON → Base64URL
4│
5├── Payload → JSON → Base64URL
6│
7└── Signature → Cryptographic signature

Both the header and the payload are JSON objects before being encoded into the final token. This makes JWT compact while retaining a structured data model.

JWT can be a good fit when:

• APIs need token-based authentication.
• Multiple services need to verify tokens.
• Tokens need to carry structured claims.
• Stateless verification is useful.
• Different applications need a common token format.

JWT may not be the best choice simply because it is popular. For a traditional server-rendered application with straightforward session management, regular server-side sessions may be simpler.