JWT

JWT — JSON Web Tokens — is the compact, self-contained, cryptographically signed token format that became the workhorse of modern API authentication and authorization. A JWT is a small, URL-safe token that carries a set of claims — assertions about identity, permissions, expiration, and other context — signed so that the recipient can verify the token hasn’t been tampered with. It sits underneath an enormous amount of modern API security: OAuth flows issue JWTs as access tokens, services pass JWTs between each other to convey identity, and the stateless verification JWTs enable is what makes them so well-suited to the distributed, microservices-heavy architectures that dominate today. JWT is one of those pieces of infrastructure that most developers use constantly without thinking much about, and understanding what it does and where it fits is essential to understanding how API authentication actually works.

The core value of JWT, the thing that made it win, is that it’s self-contained and verifiable without a round-trip. I wrote in 2017 about API message integrity with JSON Web Token — the way a JWT carries its claims and a signature together, so the recipient can verify both the integrity and the authenticity of the token using the signature alone, without having to call back to an authentication server to check whether the token is valid. This statelessness is JWT’s superpower in a microservices world: a service can receive a request, verify the JWT locally, read the claims about who the caller is and what they’re allowed to do, and proceed — all without a database lookup or a call to a central auth service. In an architecture with dozens or hundreds of services, that stateless, local verification is enormously valuable, and it’s the main reason JWT became the dominant token format for modern API authentication.

JWT lives within the broader authentication landscape, and understanding its place in that landscape is important. When I wrote my introduction to API authentication, covering the spectrum from API keys to basic auth to OAuth 1.0 and 2.0, JWT fits as the token format that modern OAuth 2.0 flows typically use for their access tokens, and as a general-purpose mechanism for conveying identity and claims between parties. JWT isn’t an authentication protocol itself — it’s a token format that protocols like OAuth use. The OAuth flow handles the dance of obtaining authorization; the JWT is what gets issued at the end and passed along with subsequent requests. This distinction matters: JWT is the envelope that carries the claims, while OAuth is the process that decides what claims you’re entitled to. The bearer token you generate and pass in an Authorization header — like the Bluesky session example I walked through in 2024 — is very often a JWT under the hood.

The claims model is JWT’s most powerful and most underappreciated feature, because it’s what lets a token carry context. A JWT’s payload is a set of claims — standardized ones like issuer, subject, audience, and expiration, plus any custom claims the issuer wants to include about the user’s roles, permissions, or attributes. This means a JWT isn’t just a meaningless access token; it’s a carrier of meaningful, verifiable assertions about who the caller is and what they can do. A service receiving a JWT can make authorization decisions based on the claims without needing to look anything up. This is what makes JWT so useful for fine-grained, distributed authorization: the token itself carries the context needed to decide what the caller is allowed to do. The claims are where JWT goes beyond simple authentication into conveying rich, structured identity and authorization information.

The security considerations around JWT are real and worth taking seriously, because the self-contained design that makes JWT powerful also creates pitfalls. Because a JWT is stateless and verified locally, revoking one before it expires is genuinely hard — you can’t easily invalidate a token that services verify without checking back with a central authority. This is why JWT expiration and refresh-token patterns matter so much: you keep access-token lifetimes short to limit the window of a compromised token, and use refresh tokens to obtain new ones. The signing matters enormously too — a JWT is only as trustworthy as the verification of its signature, and there’s a long history of JWT vulnerabilities stemming from implementations that didn’t verify signatures properly. My broader point about API authentication governance, which I wrote about in 2025 aligned with the OWASP API security risks, applies directly: broken authentication is one of the top API security risks, and JWT, used carelessly, is a frequent source of it. The token format is sound, but the implementation discipline around signing, expiration, and verification is where the real security lives.

The honest framing, which connects to my broader views on API authentication, is that JWT is a good tool within a flawed but necessary ecosystem. I wrote in 2018 that OAuth has many flaws but it’s the best we have at the moment — and the same pragmatism applies to JWT. It’s not perfect: the revocation problem is real, the implementation pitfalls are real, and the complexity it adds is real. But it solves the genuine problem of conveying verifiable identity and claims in a stateless, distributed way better than the alternatives, which is why it became ubiquitous. There’s also a deeper concern I’ve raised: the point where API session management becomes API surveillance, where the tokens that authenticate you also become the mechanism for tracking everything you do. JWTs, as carriers of identity that flow through every request, are part of that surveillance infrastructure, and the same claims that enable authorization also enable detailed tracking. The token is a tool, and like every tool in the API security stack, it can serve the consumer’s interest or be turned against it. JWT is foundational modern infrastructure — powerful, pragmatic, and worth understanding well, including its flaws — because it sits underneath so much of how APIs authenticate and authorize in the distributed systems that define the current era.

Guidance

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

References

Guidance Details

Explore more

Discover APIs