The Future of JWT.io

[DanOnCall]

We are actively working on a new version of the JWT Debugger, the application you've been using on jwt.io. We'd like to share insights with the community that uses this tool on the app's current state and future.

My name is Dan. I work at Okta in the Auth0 DevRel team as an engineer who helps build and ship digital experiences and tools for developers. I'd like to start by sharing with y'all the current state of the jwt.io app.

The Present of JWT.io

The current state of the tool allows developers to:

• Decode a JWT
• Encode and sign a JWT
• Verify the signature of a JWT
• Specify if the secret for signature verification of HMAC-signed JWTs was encoded or not using base64.
• Learn about JWTs using the introduction page.
• Explore JWT libraries using the libraries page.

The introduction and libraries pages work well. So we don't foresee major changes other than stylistic ones happening to those pages. As such, let's focus on the home page, which has the JWT Debugger Tool.

During my UX research, I spotted the following pain points in the tool:

• Decoding, encoding, and signature verification operations are mashed together in the same widget, which can create confusion about which operation is taking place and which one had any failures or errors.
• There's no clarity on the role or significance of using a "secret base64 encoded" input for the signature verification of JWTs signed with HMAC algorithms.
• Some operation errors are too generic to be helpful, and some simply never surface to the user. Error handling needs work!
• Passing a token to the site via the URL query parameters has created concerns about the token's privacy.

We'd like to address these pain points in the next version of the site.

The Future of JWT.io

What we'd like to offer in the next version to improve the UI/UX of the site is as follows:

• The Debugger would feature three widgets to handle each JWT operation: Decode JWT, Verify JWT Signature, and Encode and Sign JWT.
  • Each operation widget will have its error handling and clear instructions, allowing you to better understand why each operation may have failed and giving you insights on how to resolve the error.
• The signature verification widget will provide you encoding options for the shared secret or format options for the public key, allowing you to determine if there are formatting issues on any of the inputs to verify a JWT signature.
  • We'd also like to improve the documentation around why anyone should need or want to encode the shared secret of JWTs signed with HMAC algorithms.
• By having discrete widgets per operation, we can have cleaner business logic that allows us to focus on surfacing better errors to the end user and to handle more errors to make the tool even more helpful.
• We'd like to migrate from using URL query parameters to provide input to the JWT decoder to using URL fragments, which would be functional and available in the context of the client side only.

Let's take a peek at what these widgets could look like :)

JWT Decoder

The decoder gives you a table with the decoded data along with a description.

If you click on the "JSON" option, you can also see the JSON representation of the decoded JWT parts:

JWT Signature Verification

This widget gives you the option to verify the signature of the token:

There are two encoding formats you can specify for shared secret input:

There are two formats you can specify for public keys:

JWT Encoder

This widget allows you to create a JWT by providing JSON input for the header and payload. You can then sign the token using any of the available algorithms and providing a shared secret or private key:

Share Your Feedback

We'd love to hear from you on what has worked and not worked so far for you about using jwt.io and what your thoughts are on this future version.

[nicc777]

It probably goes without saying, but I would like a dark theme as well.

[compulim]

On paste, will be great if it can auto-remove Bearer prefix.

[samuelogboye]

These are great suggestions.

A visual indicator showing the time left before jwt expired could be helpful

[ParkerM]

My only real nitpick/gripe is how large the hero is (the part with JSON Web Tokens are an open...). It adds an extra step to what would be a keyboard only process:

1. Ctrl+L
2. j w t Enter
3. scroll the text input into view then click inside it to re-focus
   • ^ this part here
4. Ctrl+V

It also makes it slightly more difficult to align the outputs of 2 different tabs for a quick visual diff. Without the hero I could scroll both tabs to the top and their outputs would be perfectly aligned.

Love the tool and the work you've put into it. Was worried this was gonna be one of those announcements that get 800 thumbs down, but was presently surprised instead.

[ParkerM]

On paste, will be great if it can auto-remove Bearer prefix.

In the same vein it would be nice to strip Authorization and any other non-JWT header components so one could copy/paste an entire raw header line like Authorization: Bearer eyJ.... Would minimize the effort required to select and copy a huge header line using clunky tiny dev tool windows.

This is more of a nice to have and perhaps a bit too much. The Bearer thing alone would be fantastic because I run into that exact thing just about every day.

[swantzter]

My spontaneous reaction with the screenshots of the decoding part is that they don't feel compact enough. I really enjoy the current two column layout where you can easily have everything in view without scrolling for a lot of JWT:s.

For example I think the "DECODED HEADER" and "DECODED PAYLOAD" headers could live in the tab-bar (JSON/claims breakdown) with those tabs off to the right side (with a separator between them and the copy button) or even moved atop all of it to control both header and payload. Then the two boxes could stick together. with probably something similar for the signature section.

The full width layout seems like it'd be great on phones and narrow screens, but for larger screens the current two column mode is better imo. I understand the full width makes the claims breakdown with a third column for the description easier, but here too I only think that makes sense on small screens, on a laptp or desktop the compactness is much more valuable and the hover tooltips work fine

[johnmccalla]

Looks really nice! Maybe one minour suggestion would be to add the "relative time" to the unix timestamp decoding tooltip, so it also showed something like "in an hour", for example.

[Zenkylo]

Being able to capture the paste anywhere on the page as opposed to needing to focus the JWT field would be nice.

[DanOnCall]

Thank you every one for your suggestions thus far! 🙏 I appreciate the level of detail on your feedback. Keep it coming. These are nice UI/UX boosters.

[DanOnCall]

It also makes it slightly more difficult to align the outputs of 2 different tabs for a quick visual diff. Without the hero I could scroll both tabs to the top and their outputs would be perfectly aligned.

@ParkerM You may like the new sub-navigation 👀

The page loads:

You can tab into the desired navigation and sub-navigation item (I plan to use React Aria to make this nice) and press Enter:

Now, you'll quickly have the section you need "pinned" to just below the navbars and you'll have consistent UI across tabs for that visual comparison.

What do you think?

[DanOnCall]

@swantzter Do you find yourself using both the decoding and encoding features simultaneously side by side? If not, would it help your UX if you had an option to stack the "Decoder" and "Encoder" side-to-side using "tabs"?

My reasoning behind putting everything on the same page by default is that it will help search engine bots index the site and help more people find this tool for decoding/encoding :) But, I am thinking, that you could have an option to switch to a tabs layout for the two major tools.

And then, what if we give you a "compact" mode for the "Decoder" similar to how the new "Encoder" looks? "Compact encoding" could default to presenting the decoding output as JSON. The new "Claims Breakdown" is helpful for people who are just starting to learn about JWTs as they can benefit from that greater level of detail; while someone who uses the tool routinely can benefit from something less detailed and more compact. 🤔

[DanOnCall]

@swantzter This is what the compact mode could look like 🤔 I just prototyped this 😄 In compact mode, we'd also yeet the hero, helper text, and also the "alg" input which we use for examples.

(In this prototype, you'd still need to scroll down to get to the Encoder widget, but we could make that a side-to-side tab)

[swantzter]

Do you find yourself using both the decoding and encoding features simultaneously side by side? If not, would it help your UX if you had an option to stack the "Decoder" and "Encoder" side-to-side using "tabs"?

@DanOnCall sorry I was unclear, I'm in full support of having the encoder and decoder be separate tools and have them on different "pages". However now that you mention it something that would be nice is to have the decoded info carry over to the encoder when you switch tool since a fairly common usecase for me is "paste a token, edit a couple values, add the secret, copy the modified token). For the "compact" decoder you could even have a pretend three column layout and add a swiping animation if you want to be fancy about it:

+-border is the viewport
+++++++++++++++++++++++++++++++++++++++++
+ [Slected Tab: Decode], [Tab: Encode]  +
+                                       +
+ | Column 1        | Column 2         |+ Column 3
+ | Paste JWT token | Header/Body/sign |+ Encoded JWT
+ | editable        | readonly         |+ readonly
+ | visible         | visible          |+ Hidden
+++++++++++++++++++++++++++++++++++++++++

hen when you switch tab to encode the three columns "move" to the left, making column 1 invisible and column 3 visible

+-border is the viewport
                     +++++++++++++++++++++++++++++++++++++++++
                     + [Slected Tab: Decode], [Tab: Encode]  +
                     +                                       +
  | Column 1        |+ Column 2         |+ Column 3          +
  | Paste JWT token |+ Header/Body/sign |+ Encoded JWT       +
  | readonly        |+ editable         |+ readonly          +
  | hidden |        |+ visible          |+ visible            +
                     +++++++++++++++++++++++++++++++++++++++++

And then, what if we give you a "compact" mode for the "Decoder" similar to how the new "Encoder" looks? "Compact encoding" could default to presenting the decoding output as JSON. The new "Claims Breakdown" is helpful for people who are just starting to learn about JWTs as they can benefit from that greater level of detail; while someone who uses the tool routinely can benefit from something less detailed and more compact. 🤔

Yeah, I agree the claims details are useful for more unfamiliar users and I think the concept is really good. But like you say, for someone using the tool often the compact mode imo is more practical. Two notes for this: a) what mode you've selected needs to be saved with localStorage/cookies, b) you should be able to set the mode using query parameters, so you can bookmark for example https://jwt.io/decode?mode=compact and have that bookmark sync across your browsers, so you don't have to change the setting manually on every new computer

---

@DanOnCall I like your mockup of the compact mode, but what I was really getting to in my original message was that I think the compact mode should be even more compact. I don't have all your components on hand so I tried to rearrange your mockup in an image editor:

Edit: I'm imagining the JWT input field expands in height with the header and payload outputs so that the secret and signature verification are always vertically aligned

[sreepati]

Any plans on updating the libraries page? Please add a Search input instead of the current filter by.

[shvamabps]

Also, the requirement of the jwt secret key could be added as it would make the decoding of the jwt a bit more secure so that any jwt token decoding needs to provide a secret that was used to encode that token. Isn't decoding jwt tokens can be done using Buffer module in nodejs ?

[lbguilherme]

A frequent usecase for me is to copy a jwt, paste it, inspect, make a change, add the correct secret and copy the new jwt token to use elsewhere. Would it still be possible?

[Abduvohidking2004]

asdasd

[napramirez]

It will be nice to use jwt.io in getting in-depth information on the token.

It will be helpful to learn what claims are commonly used, and what claims are specific to other popular idPs.

[ParkerM]

It will be nice to use jwt.io in getting in-depth information on the token.

It will be helpful to learn what claims are commonly used, and what claims are specific to other popular idPs.

In the same vein, it would be neat if the tool showed human-friendly values for more claims. I find myself instinctively mousing over non-standard claims that look like unix timestamps because I expect the helpful tooltip to show me the parsed datetime, but it only appears for standard claims like exp and iat.

If the tool supported nonstandard claim awareness, it could simply include type information in the metadata for those claims (this is presumably how it knows exp is a unix timestamp and can be represented differently). Otherwise I guess claims' "types" could be inferred by patterns or other heuristics, but perhaps that would be excessively complex or undesirable.

[xinsight]

I'm loving that "Clear" button in the mockups! Have you ever tried to use jwt.io on a mobile device? It's unbelieveably painful to manually delete the sample jwt token before i can paste in the one i want to decode.

[DanOnCall]

Thank you, everyone, for all the feedback and validation that y'all have provided. We'll be working with our designers to iterate on this feedback and triage on what we can include. One of my commitments is to keep investing time and resources on the site to keep it up to date and expand it. Long-term, I want to bring support for JWE too!

I'll see if I can get y'all exclusive access to the MVP 👑 so that y'all can play with it and see how it feels. We'll be back into the development / design saddle after DevDay 24, so it would be around late Oct/Nov. Can't wait!

[halorgium]

I would love for the Chrome Extension to make a reappearance.

https://auth0.com/blog/amp/announcing-our-chrome-jwt-extension/

Having the UX of jwt.io in the Developer Tools is super nice, especially if there is configuration (mostly for development) associated with the site.