JWT token: what it carries and how an API should check it

A JWT token is a JSON Web Token: a compact string that carries claims about a subject, such as who a user is and until when the token is good. RFC 7519 defines the format, and in practice the token is almost always signed as a JSON Web Signature under RFC 7515. The API reads it on every request and decides whether to trust it. That makes it one way to do API authentication, and wrong checks are a named cause of broken authentication, API2 in the OWASP API Security Top 10 2023. This guide belongs to API security.

Section API security Updated Format RFC 7519

Quick facts

Defined by
RFC 7519 (the JWT format and its claims); the signed form is a JSON Web Signature, RFC 7515
Shape
Three base64url parts joined by dots: header, payload, signature
Secret?
No. A signed token proves who made it; anyone holding it can read the payload
Registered claims
iss, sub, aud, exp, nbf, iat, jti, all optional in the RFC itself
Best practice
RFC 8725, the JWT best current practices document
OWASP category
OWASP API2:2023 lists accepting unsigned or weakly signed JWTs and not validating expiry; see also the authentication failures page
Does a WAF check the signature?
No. It does not hold your key, so it cannot tell a genuine token from a forged one

Sources: RFC 7519 for claims, RFC 7515 for the compact form, RFC 7518 for algorithm names, RFC 8725 for the validation advice, and the OWASP JSON Web Token Cheat Sheet.

What a JWT token contains

The compact form has three parts separated by dots. The first two are JSON objects, each base64url-encoded; the third is the signature, also base64url. RFC 7515 calls this the JWS Compact Serialization, and the signature covers the first two parts exactly as they appear in the string.

One JWT token, as sent and as decoded (made-up values)
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImtleS0yMDI2LTExIn0
.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLTg0MTIiLCJhdWQiOiJvcmRlcnMtYXBpIiwiZXhwIjoxNzkzNzUwNDAwLCJpYXQiOjE3OTM3NDY4MDB9
.<signature bytes, base64url>

header   {"alg":"RS256","typ":"JWT","kid":"key-2026-11"}
payload  {"iss":"https://auth.example.com","sub":"user-8412","aud":"orders-api","exp":1793750400,"iat":1793746800}

The header

The header says how the token was made. alg names the signing algorithm and typ usually says JWT. A kid parameter hints at which key signed it, so a service that rotates keys can pick the right one. Every one of these values arrives from the sender, which matters in the flaws section below.

The payload and its claims

The payload is a set of claims. RFC 7519 registers seven names, listed here.

Registered claims in RFC 7519, section 4.1
ClaimMeaning
issIssuer: who created and signed the token
subSubject: who the token is about, such as a user ID
audAudience: which service the token is meant for
expExpiry: the time on or after which it must not be accepted
nbfNot before: the time before which it must not be accepted
iatIssued at: when the token was created
jtiToken ID: a unique identifier for this one token

The RFC makes none of these mandatory, so a token without exp is still a well-formed JWT. Your API decides which claims it requires. For tokens that grant API access, the OWASP cheat sheet says to require and validate iss, aud and exp, the same three that RFC 9068 mandates for OAuth 2.0 access tokens in JWT form. Where tokens are issued is covered under OAuth security. A static secret instead of a token is covered under API key security.

Base64url is an encoding, not encryption. Paste any JWT token into a decoder and the claims appear, with no key needed. The cheat sheet states it directly: a signed JWT gives integrity and authenticity but not confidentiality. Keep passwords, personal data and internal notes out of the payload. An encrypted variant, JWE, exists for the rare case that needs one.

The signature

Two families cover most tokens. With HS256, an HMAC, one shared secret both signs and verifies. With RS256, the issuer signs with a private key and every verifier uses the public key. The difference has a consequence: with a shared secret, any service able to validate tokens can also mint them, so all of those services have to be trusted equally. The cheat sheet sets out this trade-off in detail.

How an API checks a JWT token

Decoding a token tells you what it claims. Verifying it tells you whether to believe the claims. An API that only decodes has no authentication at all. The steps below follow RFC 8725 and the OWASP cheat sheet.

  1. Fix the algorithm in your own configuration. The library should receive a list of allowed algorithms and refuse everything else, and each key should be used with exactly one algorithm. The token header never chooses the check.
  2. Verify the signature with a key that belongs to the issuer. If the token names an issuer, the keys used must be that issuer's, not any key the service happens to trust.
  3. Check the time. RFC 7519 says a token must not be accepted on or after its exp. It allows a small leeway for clock skew, usually no more than a few minutes. Honour nbf the same way.
  4. Check iss and aud. The issuer must be one you expect, and the audience must include this API. Without the audience check, a token minted for one service can be replayed at another.
  5. Check what kind of token it is. A token issued for one purpose should not be accepted for another; RFC 8725 recommends explicit typing and separate validation rules for each kind.
  6. Then authorise. A valid token says who is calling, not which objects they may touch. That check is a separate job, and skipping it is BOLA.

Common JWT flaws

Most JWT incidents come from the verifier trusting something the sender controls, not from broken cryptography. Practical checks for these are on API security testing.

  • The none algorithm. RFC 7519 defines unsecured JWTs, tokens with no signature at all. RFC 8725 describes the attack: an attacker edits the header to say none, and a library that trusts the value validates the token without checking any signature. OWASP API2 lists accepting {"alg":"none"} as a vulnerability.
  • Swapping RS256 for HS256. The same RFC describes the second trick: the header is changed from RSA to HMAC, and a careless library verifies the HMAC using the RSA public key as the secret. Since the public key is public, the attacker can forge tokens. A fixed algorithm list prevents it.
  • A weak HMAC secret. A short or guessable secret lets an attacker who holds one token try guesses offline until the signature matches. RFC 8725 says human-memorable passwords must not be used directly as the key for an HMAC algorithm such as HS256.
  • Missing claim checks. No exp check means a stolen token works forever; OWASP API2 names this. No aud check allows substitution between services, as RFC 8725 explains.
  • Trusting key hints in the header. A kid value used in a database or directory lookup can carry an injection, and following a jku or x5u URL blindly can send the server to an address the attacker picked. RFC 8725 covers both.
  • Theft, because a bearer token is a key. RFC 6750 says any party in possession of a bearer token can use it. A token readable by page script is exposed to cross-site scripting, and a token in a URL ends up in logs, which OWASP API2 also flags. A cookie marked HttpOnly cannot be read by script (MDN: cookie security).
  • No way to take it back. A signature stays valid until exp. To cut off a stolen token early you need short lifetimes, a deny list on the server, or a status mechanism, and the cheat sheet notes that a deny list makes a session no longer fully stateless.

A session cookie holds a random ID, and the server keeps the session data. A JWT token holds the data and a signature, and the server keeps only keys. Neither is better in general, because each moves a different problem.

Server-side session cookie compared with a JWT token
QuestionSession cookieJWT token
What the client holdsAn opaque ID with no meaning by itselfReadable claims plus a signature
Where the state livesOn the server, looked up per requestIn the token, checked by signature
Ending a sessionDelete the server recordWait for expiry, or add a deny list
How it is sentThe browser attaches the cookie automaticallyYour code adds it, often in an Authorization header

The OWASP cheat sheet warns that JWTs are often suggested for stateless user sessions, yet session invalidation then needs a deny list, and a plain session system may serve better. Automatic attachment cuts both ways: cookies are exposed to CSRF unless you set attributes such as SameSite, while a token that is never sent automatically avoids that class. Stolen credentials of either kind lead to the same place, covered on session hijacking.

Where a WAF helps and where it does not

A WAF does not know whether a JWT token was signed with your key. It never receives the key, so a forged token with a plausible structure looks like any other request, and an expired or wrongly addressed token looks the same. Signature, exp, iss and aud checks belong in your application or API gateway, and nothing at the edge replaces them.

What a filter at the edge can still do is narrower. A rule set can check that the header is present or well formed on routes that should always carry a token. Those are shape checks and say nothing about validity. Bridge WAF itself is documented for named attack categories and per-domain rate limits, so do not count on it for token-shape rules.

Rate limits do more. Login and token endpoints are where guessing and credential stuffing land, and capping attempts per client slows them. A client that goes over the cap receives a 429 response. What counts as one client, an address or a user, is covered on per-IP vs per-user limits.

Start in monitor mode. Matches are logged while every request is still served, so you can read the monitor-mode log before turning on block. The three modes are in the box below.

Questions

What is a JWT token?

A JWT token is a JSON Web Token, a compact string with three dot-separated parts: a header, a payload of claims and a signature. RFC 7519 defines the format. An API reads the claims, such as who the user is and when the token expires, after checking the signature.

Is a JWT token encrypted?

Usually not. A signed JWT is only base64url-encoded, so anyone who holds the token can read the payload without a key. The signature proves who made the token and that it was not changed. An encrypted form, JWE, exists but is separate.

Is a JWT better than a session cookie?

Neither is better by default. A session cookie keeps data on the server and can be ended at once. A JWT keeps claims in the token, which suits stateless services but stays valid until expiry unless the server adds its own revocation check.

Can a JWT token be revoked?

Not by itself. A signed token stays valid until its exp time. To end one earlier, use short lifetimes, a server-side deny list or a token status mechanism, and accept that this adds state to a design that was meant to be stateless.

Can a WAF validate a JWT token?

No. A WAF does not hold your signing key, so it cannot verify the signature or the claims. It can rate-limit login and token endpoints and log suspicious requests, while verification stays in the application.