Auth & identity
October 4, 2023
Author: Stytch Team
In what is a JSON web token, we explored JSON web tokens (JWTs pronounced “jots”, for short) as a whole.
In this article we’ll dive into the meatiest part of a JSON web token: JWT claims.
A JSON web token is an open standard that securely relays information between clients and servers as a compact, self contained JSON object.
Simply put, it’s a form of secure communication between a client and server.
JSON web tokens’ overwhelming use case is user access management. By storing all user data client-side in the token – specifically as JWT claims – users remain both authenticated after their initial login and authorized to engage with the application according to their role and permissions.
Despite the broad range of claim values possible, all JSON web tokens take the same shape.
JWTs include three components – a header, payload, and signature – that work together to store and protect user data.
Each string is Base64url encoded and separated with a dot, so all JWTs’ final form is header.payload.signature.
Read more about the role each JWT component plays in our article, what is a JSON web token?
Now that we know the function of a JWT (secure information transmission) and its core components (header, payload, signature), we’re ready to look at JWT claims.
JWT claims are the core information that JWTs transmit (kinda like the letter inside a sealed envelope).
The JWT claims included in the payload determine which information the JWT communicates (i.e., user identity, permissions, expiration of JWT, to name a few).
That said, developers can include however many claims they want in a given payload. They can also choose the type of claim that makes sense.
JWT claims fall into three categories – registered, public, or private.
A quick formatting note: JWT claims are all three characters long no matter the type. This keeps the JWTs as compact as possible so servers can easily pass them back and forth.
Using a registered claim ensures your JWTs will operate smoothly across applications. This is because all libraries recognize these common, standardized claims.
Although it’s simplest to use registered claims, sometimes you’ll need to include user information outside the realm of those seven claims.
For example, if you want to store user metadata like email address or phone number, you’ll need to create your own custom claims.
There are two sub-categories of custom claims:
If you decide to register your custom claim, it’s critical that you name it something different than the registered claims. Collisions, in the case of JWTs, occur when a developer creates a custom claim with the same name as a registered term.
For example, if you’d like to associate a sandwich type with each user, you should not name your custom claim “sub.” Another application will read it as the registered “subject claim,” so your JWT won’t convey the user data that you want.
Stytch offers the tools to manage user access.
In addition to supporting registered claims and your own custom claims, our JSON web tokens include guardrails such as five minute expirations and automatic fallbacks to Stytch’s API once the local JSON web token expires.
You may have also seen sessions as an access management option. If you’re debating the two, you can learn more about the difference between JWTs vs. sessions on our blog.