What Is a JWT? Structure, Signatures, and Use Cases

A JWT (JSON Web Token) is a token format for exchanging information (claims) expressed as JSON in a way that lets tampering be detected. It has a three-part structure, header.payload.signature, where each part is base64url-encoded and joined with periods (.). JWTs are widely used for stateless authentication, where the server holds no session, and for API authorization. This article lays out, accurately, the structure of a JWT, the contents of each part, signatures, the crucial point that the payload is not encrypted, the use cases, and the security pitfalls.

1. What a JWT is — three parts and base64url

A JWT is a compact token format for safely exchanging claims (assertions or pieces of information) expressed as JSON. The most common form is the signed form (a JWS), which consists of the following three parts.

• header: metadata indicating the token type and the signing algorithm.
• payload: the claims you actually want to convey (who it is for, until when it is valid, and so on).
• signature: a signature over the header and payload, used to detect tampering.

Each of these three parts is base64url-encoded (a URL-safe variant of Base64) and the parts are joined with periods (.). In other words, the whole thing has this form.

base64url(header).base64url(payload).base64url(signature)

An actual token, then, is a string split into three parts, for example like this.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0Iiwicm9sZSI6ImFkbWluIn0.abc123signature

2. The contents of each part — header fields and registered claims

The header and the payload are both just plain JSON objects once decoded. Let us look at their contents in turn.

The header

The header mainly carries two fields.

• alg: the algorithm used for the signature (e.g. HS256, RS256, ES256).
• typ: the token type. Usually JWT.

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

The payload and registered claims

You can put arbitrary claims in the payload, but there are several registered claims whose meaning is defined by the specification. For interoperability, use these with their defined names and meanings.

Example: { "sub": "1234", "role": "admin", "iss": "https://auth.example.com", "exp": 1924905600 }

In this way, the payload carries the information needed for authorization: who it is (sub), what privileges they have (custom claims such as role), and until when it is valid (exp).

3. Signatures — HMAC (shared key) and RSA/ECDSA (public key)

The signature is the heart of a JWT. It is computed over the base64url-joined header and payload string and attached as the third part. There are broadly two families of signing scheme.

HMAC (such as HS256) — shared key

HMAC is a scheme where the issuer and the verifier hold the same secret key (a shared key). HS256 refers to HMAC using SHA-256. Because both the signer and the verifier need to know the same key, it suits cases where issuing and verifying happen within the same trust boundary (the same service).

RSA/ECDSA (such as RS256, ES256) — public key

RSA and ECDSA use public-key cryptography. The issuer signs with a private key, and the verifier checks it with the corresponding public key. Since you do not have to hand the private key to the verifier, this suits cases where the issuer and verifier differ (e.g. an auth server issues tokens and multiple APIs verify them with the public key).

4. The payload is not encrypted — keep secrets out

This is the most commonly misunderstood point about JWTs. The payload of a standard JWT (a JWS) is not encrypted. base64url is merely an encoding, so anyone can decode it and read its contents without any key.

Therefore, you must not put confidential information like the following in the payload.

• Passwords or fragments of them.
• Payment information such as credit card numbers.
• Personal or internal information that would be harmful if leaked.

If you need to hide the contents themselves, you have to use JWE (JSON Web Encryption), which encrypts the payload, rather than a signature-only JWS. Always keep in mind that the "JWT" used in most situations is a JWS and is not encrypted.

5. Use cases — stateless authentication and API authorization

The greatest advantage of a JWT is that the token itself carries the information it needs (it is self-contained). This lets authentication and authorization work without the server holding any session.

• Stateless authentication: after login, the server issues a JWT, and the client sends it on subsequent requests. The server can identify the user merely by verifying the signature, without consulting a session store.
• API authorization: privileges (such as role or scopes) are placed in the token, and an API uses them to decide whether to allow access. Even across microservices, each service can authorize independently if it verifies the token with the public key.
• Inter-service and third-party integration: in OAuth 2.0 / OpenID Connect, JWTs are often used to represent access tokens and ID tokens, so that the issuer signs and the recipient verifies with the public key, passing information safely.

6. Security pitfalls — alg=none, expiration, storage location

Used correctly, JWTs are powerful, but a flawed implementation can break authentication entirely. Here are the main points to watch.

• The alg=none attack: a classic attack where the header's alg is rewritten to none and the signature is left empty, getting a token accepted as "no signature verification needed." On the verifying side, fix the set of allowed algorithms and always reject none and any unexpected alg. Beware also of attackers switching the header's alg to confuse the verification logic (for example, making RS256 be mistaken for HS256 so a public key is treated as a shared key).
• Always verify the expiration: on the verifying side, check exp (and nbf / iat as needed) and reject expired tokens. Set the expiration short to minimize the damage if a token leaks.
• Storage location: when holding a token in the browser, localStorage can be read via XSS. Depending on the use case, consider a Cookie with the HttpOnly attribute, and also apply CSRF protection. In any case, the connection must be HTTPS.
• Always verify the signature: obviously, you must not skip signature verification or swallow verification errors. Verify aud and iss as well, and accept only tokens addressed to you and from a trusted issuer.