What Is a JWT (JSON Web Token)? A Complete Guide
A JWT is the token behind most modern API access, and most teams never look inside one. This guide decodes a real JSON Web Token, shows how signing and verification work, compares JWTs with opaque tokens, and lists the security mistakes that turn a JWT into an open door.

TL;DR:
What is JWT?
A JWT (JSON Web Token) is an open standard (RFC 7519) for a compact, self-contained token that carries signed claims as JSON, such as who the caller is, which API the token is for and when it expires.
It has three Base64URL parts joined by dots:header.payload.signature. An API checks the signature with the issuer's key, so it can trust the claims without a database lookup, which keeps authentication stateless.
A JWT is signed, not encrypted, so anyone can read its contents.
A support engineer pastes a partner's token into an online decoder to debug a 401. The payload opens up in plain text: the partner's internal account ID, a contact email, and a scope of *. That one token reaches every API you run, and anyone who copies it from the ticket can read what it grants.
That's the most common misunderstanding about the JSON Web Token. Teams treat it as a sealed envelope. It's a postcard with a tamper-proof seal: anyone can read it, nobody can change it without breaking the seal. Get that wrong and JWTs leak data and grant too much. Get it right and they're the fastest, most portable way to carry API access.
So, what is JWT in practice? This guide decodes a real JWT token part by part, explains how does JWT work from issue to verification, compares JWTs with opaque tokens, and lists the mistakes behind real JWT vulnerabilities, with the fix for each.

What is a JWT?
A JWT is a standard format for passing signed claims between two parties. The issuer (usually an authorization server) signs a small JSON object. The receiver (usually your API or its gateway) checks the signature and then trusts what's inside. You pronounce it "jot".
JSON Web Token (JWT)
A JSON Web Token is "a compact, URL-safe means of representing claims to be transferred between two parties," as defined in RFC 7519 (May 2015). A claim is a single statement about the token's subject, such as its ID, its audience or its expiry time.
You meet JWTs everywhere in API access:
- OAuth 2.0 access tokens. Many authorization servers, including Okta, Auth0 and Keycloak, issue access tokens as JWTs. RFC 9068 (October 2021) standardises that format.
- OpenID Connect ID tokens. An ID token, which tells an app who signed in, is always a JWT. See OpenID Connect explained.
- Single sign-on (SSO). One sign-in produces a token that several apps or domains accept, because each can verify the same signature.
- Service-to-service and AI agent calls. A microservice or an AI agent presents a JWT to prove which client it is and what it may do.
- Information exchange. Two systems pass verified data, such as an order ID or a tenant, and the receiver knows it wasn't changed on the way.
A JWT is a token format, not a protocol. OAuth 2.0 decides how a token is issued. JWT decides what the token looks like. We unpack that difference in OAuth 2.0 vs JWT.
Is a JWT encrypted?
No. A standard JWT is signed, not encrypted. The header and payload are only Base64URL-encoded, which anyone can reverse. The signature proves the token wasn't changed. It doesn't hide anything.
The JWT standard builds on a family of specs, together called JOSE (JSON Object Signing and Encryption):
- JWS, RFC 7515: a signed token. This is what people mean by "a JWT" 99% of the time.
- JWE, RFC 7516: an encrypted token, with five parts instead of three. Use it when the claims themselves are sensitive.
- JWK, RFC 7517: a JSON format for keys. A set of public keys published by the issuer is a JWKS (JSON Web Key Set).
- JWA, RFC 7518: the list of algorithms, such as RS256 and ES256.
Rule of thumb: if you wouldn't print it on the outside of an envelope, don't put it in a JWT payload. And always send JWTs over HTTPS: a token sent in clear text can be copied and replayed.
What does a JWT look like?
A JWT is three Base64URL strings separated by two dots: header, payload and signature. Base64URL is Base64 made safe for URLs: it uses - and _ instead of + and / and drops the = padding. It's encoding, not encryption, so anyone can reverse it.
Here's a real JWT token, signed with RS256. Paste it into any JWT decoder and you'll see the claims below.
eyJhbGciOiJSUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ims3In0.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJhcHBfcGFydG5lcl8yMjEiLCJhdWQiOiJvcmRlcnMtYXBpIiwiaWF0IjoxNzY3MjI0NzAwLCJleHAiOjE3NjcyMjU2MDAsImp0aSI6IjlmMWMyZTdhIiwic2NvcGUiOiJvcmRlcnM6cmVhZCIsImNsaWVudF9pZCI6InBhcnRuZXItYXBwLTIyMSJ9.ZOTetejvs1A9QkwCB8P88bvKa8ZyRaAPzgXvrCxpiUeyw6ULcDdR3NX8JD5oQ_2jRHOjJ28-Rr3ZPaEbWgvgB6m6PXzAlUkRoeff4osqifhbUXAS55Cjb4Ov7wTxRzbzWLaDoPaLTgE2ynL0hoFZUVReldzY-CDY5Coy-TqQVUdmTl0Uz5wlYvA1YbzVlfSOUQDRThCB7Es0ZiwHx1QV6ezLhnE-Dn5VgeXuzkI_-sE6PlF5flHKq1X7oIKr5zp8QZHUEAWLYPKkbo_dQeZThyikZv5GAigv6yd-bLWCkJBL0POwbPEi5i2N9CtBV1fxC3BugKJT184sJ4xPv-bsag
Part 1: the header
The header says how the token was signed and which key to use.
{
"alg": "RS256",
"typ": "at+jwt",
"kid": "k7"
}alg: the signing algorithm. RS256 means RSA with SHA-256.typ: the token type.at+jwtmarks it as an OAuth access token, per RFC 9068.kid: the key ID. It tells the API which public key in the issuer's JWKS to check against.
Part 2: the payload and its claims
The payload holds the JWT claims. This one says partner app 221 may read orders from orders-api for 15 minutes.
{
"iss": "https://auth.example.com",
"sub": "app_partner_221",
"aud": "orders-api",
"iat": 1767224700,
"exp": 1767225600,
"jti": "9f1c2e7a",
"scope": "orders:read",
"client_id": "partner-app-221"
}RFC 7519 defines seven registered claims. All seven are optional in the base standard, but your API should require the ones it relies on.
JWT registered claims (RFC 7519)
| Claim | Name | What it means | What your API should check |
|---|---|---|---|
iss | Issuer | Who created and signed the token | It matches an issuer you trust |
sub | Subject | Who or what the token is about (user, app or agent) | It maps to a known identity |
aud | Audience | Which API the token is for | It names this API |
exp | Expiration time | When the token stops working (Unix time) | It's in the future |
nbf | Not before | When the token starts working | It's in the past |
iat | Issued at | When the token was created | It's not unreasonably old |
jti | JWT ID | A unique ID for this token | It's not on a revocation list or reused |
Swipe sideways to see all columns →
RFC 7519 sorts claims into three types:
- Registered claims: the seven above. Their names are three letters long to keep tokens compact.
- Public claims: names listed in the IANA JSON Web Token Claims registry, such as
scopeandclient_id, or names made collision-proof with a URI likehttps://example.com/tenant. - Private claims: names that the issuer and your API agree on between themselves, such as
partner_tier. Check the registry before you invent one.
Part 3: the signature
The signature is the issuer's cryptographic signature over header.payload. Change one character in either part and the signature no longer matches. That's what makes a JWT tamper-evident: anyone can read it, but only the holder of the signing key can produce a valid one.
Here's how the signature is built for the two most common algorithms:
// HS256: one shared secret signs and verifies
HMACSHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
secret
)
// RS256 (our example): the issuer's private key signs, the public key verifies
RSASHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
privateKey
)How does JWT work?
A JWT moves through five steps: the client asks for it, the issuer signs it, the client carries it, the API verifies it, and the token expires. Because the API verifies the signature locally, it doesn't need to call the issuer or a database on every request. That's the main reason JWTs scale so well.

Here's how does JWT work for a partner app calling your API:
- The client asks for a token. The partner app authenticates to the authorization server, for example with the OAuth 2.0 client credentials flow. For a person, this step is a normal sign-in.
- The authorization server signs a JWT. It builds the header and payload, signs them with its private key, and returns the token. The client keeps it in memory, a secrets store, or an HttpOnly cookie.
- The client sends the JWT with each request. It goes in the
Authorization: Bearer <token>header, which makes it a bearer token. - The API verifies the token. It fetches the issuer's public key from its JWKS (once, then caches it), checks the signature, then checks the claims.
- The token expires. After
exp, it's rejected. The client gets a fresh one.
How is a JWT signed and verified?
Signing turns header.payload into a signature with a secret or private key. Verifying recomputes or checks that signature with the matching key. There are two families of algorithms:
- Symmetric (HMAC, such as HS256): one shared secret signs and verifies. Every service that verifies tokens can also forge them.
- Asymmetric (RSA or ECDSA, such as RS256 or ES256): a private key signs, a public key verifies. Your APIs only hold public keys, so a compromised API can't mint tokens. HS256 is faster, but the shared secret is harder to distribute safely.
The issuer publishes its public keys at a JWKS URL, usually /.well-known/jwks.json. The kid in each token header picks the key. To rotate keys, the issuer adds a new key to the JWKS, starts signing with it, and removes the old one after the last old token has expired.
{
"keys": [
{
"kty": "RSA",
"kid": "k7",
"use": "sig",
"alg": "RS256",
"n": "0vx7agoebGcQSuu...",
"e": "AQAB"
}
]
}Verifying vs validating a JWT. Verification checks the token is genuine: the signature matches a trusted key. Validation checks the token is acceptable right now: the structure is correct, exp and nbf fit the current time, and iss, aud and scope match. An API needs both. Decoding does neither.
Which JWT signing algorithm should you use?
For API access, use an asymmetric algorithm: RS256 if you need the widest support, ES256 or EdDSA if you want smaller, faster signatures. Use HS256 only when the issuer and the verifier are the same service.
JWT signing algorithms compared
| Algorithm | Type | Who can verify | Who can sign | Best for |
|---|---|---|---|---|
| HS256 | Symmetric (HMAC + SHA-256) | Anyone with the shared secret | Anyone with the shared secret | One service that issues and checks its own tokens |
| RS256 | Asymmetric (RSA + SHA-256) | Anyone with the public key | Only the private key holder | Multi-API and partner access; widest library support |
| ES256 | Asymmetric (ECDSA P-256 + SHA-256) | Anyone with the public key | Only the private key holder | Same as RS256, with much shorter signatures |
| EdDSA (Ed25519) | Asymmetric | Anyone with the public key | Only the private key holder | New systems where every library supports it |
none | Unsigned | Nobody: there is no signature | Anyone | Never accept it |
Swipe sideways to see all columns →
What are the benefits and limitations of JWTs?
JWTs make authentication stateless, portable and fast, but they're hard to revoke early and they expose their contents. Know both sides before you choose them.
Benefits
- Stateless and scalable. The API keeps no session store. Any server with the public key can check any token.
- Portable across services and domains. Claims travel with the token, so microservices, gateways and SSO apps all read the same facts. Sent in a header rather than a cookie, a JWT isn't attached to requests automatically, which closes off cross-site request forgery (CSRF). Cross-origin APIs still need CORS rules that allow the
Authorizationheader. - Compact and standard. A JWT fits in an HTTP header, and every major language has a library for it.
- Tamper-evident. Any change to the header or payload breaks the signature.
Limitations
- Hard to revoke early. A JWT stays valid until
expunless you add a denylist, introspection, or very short lifetimes with refresh tokens. A refresh token is a longer-lived, usually opaque credential that the client trades for new access tokens. The server can revoke it, and that's how "log out" works with JWTs: kill the refresh token and let the short access token expire. - Readable payload. Anyone holding the token can decode the claims, so personal data and secrets don't belong there.
- Size on every request. Each claim adds bytes to every call. Big tokens slow traffic and can break header limits.
- Easy to validate badly. The format leaves choices, like the algorithm, that weak libraries get wrong. More on this below.
JWT vs opaque tokens: which should your API use?
A JWT carries its own claims, so the API verifies it locally. An opaque token is a random string, so the API asks the authorization server what it means. JWTs win on speed and scale. Opaque tokens win on privacy and instant revocation.

JWT vs opaque token
| Dimension | JWT (self-contained) | Opaque token (reference) |
|---|---|---|
| What it contains | Signed claims anyone can decode | A random string with no meaning |
| How the API checks it | Verifies the signature locally with a cached public key | Calls the introspection endpoint (RFC 7662) |
| Latency per request | None beyond the crypto check | One network call (often cached) |
| Revocation | Takes effect at exp, unless you add a denylist | Instant: the server says "inactive" |
| Privacy | Claims are visible to the client and anyone who copies it | Nothing is exposed |
| Size | Often 500 bytes to 2 KB; grows with claims | Usually 32 to 64 characters |
| Works offline / across clouds | Yes, if the API has the JWKS | No, needs the authorization server |
| Best for | High-volume APIs, microservices, multi-gateway estates | Third-party clients, sensitive data, instant revoke needs |
Swipe sideways to see all columns →
Many teams use both: opaque tokens for clients outside the company, swapped for short-lived JWTs at the gateway for internal hops. That's often called the "phantom token" pattern.
How are JWTs used for API access?
JWTs carry the decision "this client may call this API with these scopes until this time" from the authorization server to every API that needs it. The gateway verifies each JWT once at the edge, then passes the verified identity and scopes to the backend.
A well-configured API gateway runs these checks, in this order, on every request. RFC 8725, the JWT Best Current Practices (February 2020), is the source for most of them.
1. Token present in Authorization: Bearer, three dot-separated parts → else 401
2. alg is on your allow-list (e.g. RS256, ES256); reject "none" → else 401
3. kid matches a key in the trusted issuer's cached JWKS → else 401
4. Signature verifies with that key → else 401
5. typ is "at+jwt" for access tokens (RFC 9068) → else 401
6. iss is trusted, aud names this API → else 401
7. exp in the future, nbf in the past (allow ~60s clock skew) → else 401
8. jti not on the revocation list (for high-risk routes) → else 401
9. scope / roles cover this route and method → else 403The hard part isn't writing these checks. It's keeping them identical across every gateway you run. In large API programs, Kong, Apigee, AWS API Gateway and Azure API Management often sit side by side. One checks aud, another doesn't. One accepts 24-hour tokens, another 15 minutes. One still trusts a retired signing key. Each gap is a way in.
This is where an API management layer earns its place. The DigitalAPI API Gateway validates JWTs against OAuth, OIDC, Keycloak and Okta issuers, so one token policy covers every gateway you run. Teams using the DigitalAPI API Developer Portal let partners request access and get scoped, short-lived tokens on their own, instead of waiting days for credentials sent by email.
See how DigitalAPI keeps every JWT scoped, short-lived and validated the same way across your gateways → Book a Demo
How do AI agents use JWTs?
AI agents that call APIs through the Model Context Protocol (MCP) present OAuth 2.1 access tokens, which are usually JWTs. The MCP authorization spec says servers "MUST validate that access tokens were issued specifically for them" and must never pass a client's token through to another API. In JWT terms: check aud every time.
The risk with agents is speed. An agent with a broad JWT can make thousands of calls before anyone notices. Give each agent its own client identity, scope its tokens to the tools it needs, and keep lifetimes short. The DigitalAPI MCP Gateway issues per-agent credentials with per-tool scopes and logs every call, so you can see what each agent did. For the full setup, see securing MCP endpoints.
What are the most common JWT security mistakes?
Almost every JWT vulnerability comes from the API trusting the token before it has verified it properly. The format is sound. The bugs live in libraries and configuration. OWASP lists "accepts unsigned/weakly signed JWT tokens" and "doesn't validate the JWT expiration date" under API2:2023 Broken Authentication, the second most critical API risk.
The stakes are real. The Verizon 2025 Data Breach Investigations Report found credential abuse was the top way attackers got in, at 22% of breaches. And Salt Security's 2025 State of API Security report found that 95% of API attacks came from authenticated sources: callers holding a valid token.
Here are the mistakes behind real JWT vulnerabilities, and the fix for each:
- Accepting
alg: none. An attacker strips the signature and setsalgtonone. A library that honours the header accepts it. Real example: in CVE-2022-23540, Node'sjsonwebtoken(up to 8.5.1) could fall back tononewhen no algorithms were set. Fix: pin an allow-list of algorithms on the verifier. Never read it from the token. - Algorithm confusion (RS256 to HS256). The attacker switches
algto HS256 and signs with your public key as the HMAC secret. A careless library verifies it. Real examples: PyJWT (CVE-2022-29217) and python-jose (CVE-2024-33663). Fix: bind each key to one algorithm. - Trusting
kid,jkuorx5ublindly. These headers point to the key. If the API follows them to an attacker's URL or file, the attacker picks the key. Fix: only look keys up in your own cached JWKS from a pinned issuer URL. - Skipping
audandisschecks. A valid token for one API gets replayed against another. A 2025 flaw infast-jwt(CVE-2025-30144) let a craftedissarray bypass issuer validation. Fix: require exactissandaudmatches on every API. - Putting secrets or personal data in the payload. The payload is readable, as our opening example shows. Fix: carry IDs and scopes only. Use JWE if claims must be private.
- Long lifetimes and no revocation. A JWT that lasts 30 days works for 30 days after it leaks. Fix: 5 to 60 minute access tokens, refresh tokens for renewal, and a
jtidenylist for emergencies. - All-access scopes. One token with
scope: *turns a small leak into full access. Fix: issue the narrowest scope per client, per API. - Storing JWTs in
localStorage. Any script on the page, including an injected one, can read it. Fix: prefer HttpOnly, Secure, SameSite cookies or in-memory storage, or keep tokens server-side. - Huge tokens. Every claim adds bytes to every request. Nginx's default header buffer is 8 KB per header line, and requests over it fail with 400. Fix: keep claims lean and look up the rest server-side.

What are the JWT best practices?
Verify everything, trust nothing in the header, and keep tokens short-lived and narrow. As of November 2026, an update to RFC 8725 that covers attacks found since 2020 is in the IETF publication queue, so expect these rules to tighten, not loosen.
- Pin allowed algorithms on the verifier, and prefer RS256, ES256 or EdDSA for multi-service access.
- Validate signature,
iss,aud,exp,nbfandtypon every request, at the gateway. - Fetch keys only from a trusted JWKS URL, cache them, and rotate keys on a schedule.
- Keep access tokens to 5 to 60 minutes, and use refresh tokens to renew them.
- Put IDs and scopes in the payload, never passwords, API keys or personal data.
- Issue the narrowest scope per client, and a separate identity per AI agent.
- Keep a
jtidenylist or introspection fallback for tokens you must kill instantly. - Send JWTs only over HTTPS, and never in URLs.
- Keep signing keys in a KMS or HSM. A leaked private key lets anyone mint valid tokens until you rotate it.
- Keep your JWT library patched. Most JWT CVEs above were fixed by a library upgrade.
Should you use JWTs for your API?
JWTs are the right default for most APIs with many callers and many services, as long as you validate them strictly and keep them short-lived. Use the decision block below.
JWTs are right for you if
- Several APIs, gateways or clouds need to check the same token without calling a central server.
- You need tokens that carry scopes, audience and expiry for partners, customer apps or AI agents.
- You already run an OAuth 2.0 or OpenID Connect provider that can sign tokens and publish a JWKS.
JWTs are not the best fit if
- You must revoke access instantly, every time. Use opaque tokens with introspection, or add a denylist.
- The token would carry sensitive data that clients shouldn't see. Use opaque tokens or JWE.
- One server-rendered web app is your only client. A server-side session cookie is simpler.
Key takeaways
- A JWT (JSON Web Token) is signed JSON in three parts:
header.payload.signature. - It's signed, not encrypted. Anyone can read the payload, so never put secrets in it.
- APIs verify JWTs locally with the issuer's public key from a JWKS, so they scale without a lookup.
- JWTs beat opaque tokens on speed. Opaque tokens beat JWTs on privacy and instant revocation.
- Most JWT breaches come from weak validation:
alg: none, algorithm confusion, untrustedkid, or missingaudchecks. - Enforce one strict validation policy at the gateway, the same way, for apps and AI agents alike.
Frequently asked questions
1. What is the point of JWT?
The point of a JWT is to let one system trust facts about a caller without asking anyone. It's used mostly as an OAuth 2.0 access token that lets a client call an API, as an OpenID Connect ID token that tells an app who signed in, and for single sign-on. Because the API verifies the signature on its own, JWTs work well for microservices, multiple gateways and AI agents.
2. What does JWT authentication mean?
JWT authentication means the client proves who it is by sending a signed JSON Web Token with each request, usually in the Authorization: Bearer header. The server checks the signature and claims, such as issuer, audience and expiry, instead of looking up a session. If the checks pass, the request is authenticated.
3. How do you pronounce JWT?
JWT is pronounced "jot", as RFC 7519 recommends. Many people also say the letters, "J-W-T". Both are understood.
4. Is JWT the same as OAuth?
No. OAuth 2.0 is a framework for deciding how a client gets access to an API. JWT is a token format. An OAuth authorization server often issues its access tokens as JWTs, but OAuth can also use opaque tokens, and JWTs are used outside OAuth too.
5. Can anyone decode a JWT?
Yes. The header and payload are Base64URL-encoded, not encrypted, so anyone holding a JWT can read its claims with a decoder. What they can't do is change those claims without breaking the signature. If the claims must stay private, use an encrypted JWT (JWE) or an opaque token. Decoding is also not verifying: a token that decodes fine may still be forged or expired, so an API must check the signature and claims before it trusts anything inside.
6. What happens if a JWT is stolen?
A stolen JWT works for whoever holds it until it expires, because a standard JWT is a bearer token. Limit the damage with short expiry times, narrow scopes and an audience claim. For high-value APIs, bind tokens to the client with mTLS or DPoP so a copied token can't be replayed.
7. Can a JWT never expire?
Technically yes, because the exp claim is optional in RFC 7519. In practice, a JWT without exp is a permanent credential that can't be revoked without extra machinery. Always set exp, keep access tokens to an hour or less, and have your API reject tokens that lack it.
8. Is JWT obsolete? What's better than JWT?
No. JWT is still the most widely used token format for APIs, and new standards such as RFC 9068 and the MCP authorization spec build on it. Alternatives like PASETO remove some risky options such as algorithm choice, and opaque tokens trade speed for instant revocation. The bigger risk is poor validation, not the format.
9. How big can a JWT be?
RFC 7519 sets no maximum, but servers do. Nginx's default allows 8 KB per header line, AWS Application Load Balancer allows 16 KB per header, and browser cookies top out around 4 KB. Keep JWTs under about 2 KB by carrying IDs and scopes, not full user profiles.
10. What's the difference between JWT and a session cookie?
A session cookie holds a random ID, and the server looks up the session in its own store on every request. A JWT carries the claims itself, so any service with the public key can verify it without a lookup. Sessions are simpler for one web app. JWTs suit APIs called by many clients and services.
11. How is JWT different from SAML?
Both carry signed identity claims, but a JWT is JSON while a SAML assertion is XML. JWTs are much smaller, simpler to sign than XML Digital Signature, parse natively in every language and fit in an HTTP header, which makes them the default for APIs and mobile apps. SAML is still common for older enterprise single sign-on.
12. Can I use JWT in Python?
Yes. PyJWT and Authlib are widely used Python libraries for creating and verifying JWTs. Whatever library you pick, pass an explicit list of allowed algorithms when you verify, require exp, iss and aud, and keep the library patched: PyJWT's CVE-2022-29217 was an algorithm-choice flaw fixed in version 2.4.0.
Conclusion
So, what is JWT? It's a signed, readable, self-contained set of claims, and it's the credential behind most modern API access. The format does one thing well: it lets any API trust a token without asking anyone. That strength is also the risk. A JWT trusted too easily, scoped too widely or kept too long becomes the easiest way into your APIs.
The fix sits at the edge. Validate every JSON Web Token the same strict way on every gateway, keep tokens short-lived and narrow, and give every partner and AI agent its own identity. Start this week by checking whether all your gateways verify aud and pin their algorithms. That's where most JWT gaps hide.
How safely do you grant API access to partners and AI agents? Get your free readiness score: Check Your API Access Readiness
Prefer a walkthrough? Book a Demo
One email a fortnight. Worth opening.
A short digest of what we're writing, what we're learning from customers, and the handful of links you'd actually want from us. No tracking pixels.













.avif)
