JWT claims

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.

Back up: what is a JSON web token?

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.

Structure of a JSON web token

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?

So, what is a JWT claim?

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.

Types of JWT claims

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.

Registered claims

Registered claims are pre-established and publicly documented. Below are the seven registered claims found in the official Internet Assigned Numbers Authority (IANA) and JWT databases:

• Issuer Claim (“iss”): which application issued the JWT?
• Subject Claim (“sub”): who is the user subject of the JWT?
• Audience Claim (“aud”): which application is the JWT intended for?
• Expiration Time Claim (“exp”): until what date/time can the JWT be accepted?
• Not Before Claim (“nbf”): what date/time can the JWT start being accepted?
• Issued At Claim (“iat”): when was the JWT issued?
• JWT ID Claim (“jti”): which individual JWT is this?

Using a registered claim ensures your JWTs will operate smoothly across applications. This is because all libraries recognize these common, standardized claims.

Custom 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:

1. Public claims: Developers define their own claims and register them with the IANA registry mentioned above.
2. Private claims: Developers define their own claims but do not publish them. Instead, they make local agreements to ensure operability between private parties.

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.

Manage user access with Stytch

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.