Should I Say JWT or JWT Token, or JWS Token Or…?

fleeting
Table of Contents

Should I say JWT or JWT token, or JWS token, or what ?

TL;DR: none of the above, this is a red herring and one should name the token by its function instead of its nature.

At first, I thought that the expression JWT token was a repetition of the word token (it literally means JSON Web Token token) and I thought that this repetition was a mistake. As I hope I make clear enough in the following lines, I was wrong considering this as a mistake by repetition.

I read the definition again.

JSON Web Token (JWT) is a compact claims representation format

https://datatracker.ietf.org/doc/html/rfc7519

JWT is the name of a format, a mean to store information in a standardized manner.

But in the same time, the letter T means Token, suggested that we are not talking about a format, but about a concrete piece of data.

A token is generally defined as a small piece of data shared between several actors. Hence, to me, naming a format “token” makes things ambiguous in the first place, but the “correct” way of naming things is another debate.

OAuth 2.0 itself uses JWT to refer alternatively to a format and to a token encoded in this format1.

In addition, when one refers to a JWT/JWT token, per generally refer to something encoded in JWS or JWE. Hence, one would be totally right calling it a JWS token (or, using the same shortcut a JWS) or JWE token (or simply JWE) as well.

It sounds to me right to speak about a “JPEG photograph”, a “MP4 movie” or a “MP3 music”. Hence I think I am not shocked in general by the expression “a <format> <object>”. Hence, if one talks about a particular piece of data and calls it a JWT token, I think it should be ok.

Likewise, saying a “JWT” should be ok with me, like saying a “MP3” or a “JPEG”. It is like saying this piece of data encoded in JWT, about which I have no clue but the fact it is encoded in JWT.

Well, in fact, I am not totally ok with both.

First of all, even though it sounds grammatically correct to say “this JPEG photograph”, no one actually says that! People would rather tell “this photograph of a house” (or whatever they see in the photograph). The fact the format is JPEG is important only when the discussion is about the format itself, like “this photograph of a house is encoded in JPEG, I hope it is ok with you.”

Also, when people talk about this of that “JWT”, they seldom mean that they don’t know or don’t care what is behind the encoding. They are referring to a token that is to be used in a precise manner. The simple fact that they say “JWT” and not simply “token” is a hint that they care about what it is made of.

As a conclusion, I believe that referring to a token as “JWT” or “JWT token” are both wrong, but in a few exceptions. To me, they convey the fact that the person mentioning them likely not understand what per is talking about well enough to be more precise. In that case, I would suggest the conversation stops and the function of the token is made clear to avoid having a false sense of understanding each other.

What will I do then? I decided that I’d rather call a token by its intent rather than the way it is encoded. It might be an access token, an ID Token or a totally different thing.

Even in the cases I need to indicate the format, chances are that saying it is JWT would be not enough and that I would have to indicate the serialization as well. I would rather tell something like “this access token, encoded in JWT and compactly serialized in JWS”.

Some people would say that “this is waaaaay too long in a conversation”, as if it is a good excuse to say “JWT token” in the first place. Those are likely in cognitive dissonance and should consider saying access token, id token (or whatever the token is made for) instead of “JWT token”. It is likely to be shorter to pronounce and to convey a more useful meaning in the conversation.

Notes linking here


  1. The distinction between an access token and a JWT is subtle. An access token represents a delegated authorization decision, whereas JWT is a token format. An access token can be formatted as a JWT but doesn’t necessarily have to be. And a JWT might well be an access token, but not all JWTs are access tokens.

    https://datatracker.ietf.org/doc/html/rfc8693#section-3

     ↩︎