What Is a JWT? Structure, Claims and Signing Explained
A JWT is three base64url parts, header.payload.signature. Anyone can decode it, so a decoded token proves nothing until the signature is verified.
A JSON Web Token (JWT) is a compact string of three base64url-encoded parts separated by dots: header.payload.signature. The header says how the token is signed, the payload carries claims such as who the user is and when the token expires, and the signature lets the receiving server detect tampering. Anyone holding a token can decode and read the first two parts, so a successfully decoded JWT proves nothing by itself. Trust comes only from verifying the signature with the right key. JWTs are defined in RFC 7519.
The three parts
| Part | Contents | Encoding |
|---|---|---|
| Header | JSON such as {"alg":"HS256","typ":"JWT"}: the signing algorithm and token type |
base64url |
| Payload | JSON claims about the subject and the token | base64url |
| Signature | A cryptographic signature or MAC over header.payload |
base64url |
The signature covers the encoded header and payload joined by a dot, exactly as transmitted. That is why changing even one character of the payload invalidates it.
base64url, not base64
Standard base64 uses + and / and pads with =, which cause trouble in URLs and HTTP headers. JWTs use the base64url variant from RFC 4648: - replaces +, _ replaces /, and the = padding is dropped. The three bytes 0xFB 0xFF 0xFE encode to +//+ in base64 and -__- in base64url. To decode by hand you add the padding back so the length is a multiple of 4. This is encoding, not encryption: it hides nothing.
Registered claims
RFC 7519 defines a short list of standard claim names. All are optional, and applications add their own.
| Claim | Meaning |
|---|---|
iss |
Issuer: who created the token |
sub |
Subject: who the token is about |
aud |
Audience: who the token is intended for |
exp |
Expiration time (seconds since the Unix epoch) |
nbf |
Not before: the token is invalid before this time |
iat |
Issued at |
jti |
A unique token ID |
Time claims are whole seconds since 1970-01-01 UTC, not milliseconds. A receiver must check exp, aud and iss itself; a library will not always do it for you unless you configure it.
Signing is not encryption
A typical JWT is signed (a JSON Web Signature, RFC 7515): readable by anyone, tamper-evident to anyone with the key. A JWT can also be encrypted (a JSON Web Encryption, RFC 7516) so only the key holder can read it, but that is a different format with five parts, and it is much less common. Because ordinary tokens are only signed, never put passwords, API keys or private data in the payload.
Signing algorithms come in two families. HS256 is symmetric: the same secret signs and verifies, so every verifier must be trusted with it. RS256 and ES256 are asymmetric: a private key signs and a public key verifies, so many services can verify without being able to issue tokens.
A worked example
This Python builds a demo token with the made-up secret demo-secret-not-real (a placeholder, not a real credential):
import base64, hmac, hashlib, json
def b64u(b):
return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
header = {"alg": "HS256", "typ": "JWT"}
payload = {"iss": "https://auth.example.test", "sub": "user-1001",
"aud": "demo-api", "iat": 1793577600, "exp": 1793581200,
"role": "reader"}
h = b64u(json.dumps(header, separators=(",", ":")).encode())
p = b64u(json.dumps(payload, separators=(",", ":")).encode())
mac = hmac.new(b"demo-secret-not-real", f"{h}.{p}".encode(), hashlib.sha256)
print(f"{h}.{p}.{b64u(mac.digest())}")
The output is this token (241 characters):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS50ZXN0Iiwic3ViIjoidXNlci0xMDAxIiwiYXVkIjoiZGVtby1hcGkiLCJpYXQiOjE3OTM1Nzc2MDAsImV4cCI6MTc5MzU4MTIwMCwicm9sZSI6InJlYWRlciJ9.cBElLAirrzJ2xxh6e4Rh23EZkPODHHERLB55zLMCWjM
Decoding the first part gives {"alg":"HS256","typ":"JWT"}. Decoding the second gives:
{"iss":"https://auth.example.test","sub":"user-1001","aud":"demo-api","iat":1793577600,"exp":1793581200,"role":"reader"}
Here iat is 2026-11-02 00:00:00 UTC and exp is 3,600 seconds later, 01:00:00 UTC, so the token lives for one hour. The third part, cBElLAirrzJ2xxh6e4Rh23EZkPODHHERLB55zLMCWjM, is 43 characters: the 32-byte HMAC-SHA-256 output in base64url.
Why decoding is not verifying
Decoding just reverses base64url. Verifying means recomputing the signature over header.payload with the key and comparing it to the third part. Suppose someone edits the payload to say "role":"admin" and re-encodes it, leaving the old signature in place. The decoded token now reads as an admin token. Recomputing the HMAC with the real secret gives a different value, so verification fails. In the Python check for this example, the original token verifies and the edited one does not.
Common mistakes follow from confusing the two:
- Trusting claims from a decoded token without checking the signature.
- Letting the token choose the algorithm. Accept only the algorithms you expect, and reject
none. - Skipping the
exp,audorisschecks after the signature passes. - Storing sensitive data in the payload because it “looks” unreadable.
Try it
Paste a token into the JWT decoder to see its header, payload and expiry time in readable form. It can also check an HMAC signature if you supply the secret; without the key, a decoded token cannot be called genuine. To reproduce the decoding steps on any single part, use the Base64 encode and decode tool. The token above and every number in this guide were produced with Python’s standard library, and the format rules come from RFC 7519, RFC 7515 and RFC 4648.
Updated 2026-11-02