JWT.io v2 Changelog

[DanOnCall]

🎉 Update: The beta is now complete and we've kickstarted an A/B test for v1 vs v2. We'll continue to iterate on feedback shared on this issue, so please keep it coming. For now, you no longer need to enter any passcode to access v2. If you get v1, clear your cookies, refresh, and if the random algo is on your side, you'll get group B (v2).

TL;DR: Please try out the prototype of JWT.io v2 and share feedback with us any feedback that you may have to help us ship an even better JWT debugger than what we had before:

• Head to https://jwt.io/beta

As mentioned in "The Future of JWT.io", we have been actively working on a new version of the JWT Debugger, and now we have a working prototype that y'all can try out.

Please help us stress test it by using it as you would use JWT.io. We are eager to balance better UI/UX with better design while upholding the most important value proposition of the site: it's a developer tool. Your feedback is critical for us to ship this experience, as we don't want to ship anything that will prevent you from enjoying using this tool. Please reply with your feedback (the good, the bad, and the ugly) or react with emojis--that works too! 🚀

Below is a list of all new features, deprecations, and notable changes (so far) for the migration of JWT.io from v1 to v2.

Notable Changes

New JWT widgets

• We have divided the JWT Debugger tool into two main widgets, each handling a different JWT operation to provide better error handling and user feedback.
• A JWT decoder
  • The decoder takes as input a JWT and outputs its decoded header and payload.
  • You can see the decoded output as a JSON object or as a table that includes helpful descriptions, tips, and other metadata about the claims.
    • Time-related claims, such as exp and iat, show you the date in a human-readable format.
    • The decoder now warns you when a JWT has expired.
    • You can input a secret or public key to verify its signature.
    • We have improved communication about the different encodings and formats that secrets and public keys can have, respectively.
    • Secret: UTF-8 and base64url encoding.
    • Public Key: PEM or JWK formats.
  • ✨ The decoder now supports decoding unsecured JWTs.
  • ✨ Decoding and verifying the signature of JWTs signed with the EdDSA (Ed25519) algorithm is now supported.
    • This support is only available on the Firefox and Safari browsers. Learn more about the browsers that support this algorithm here.
    • Chrome has provided experimental support since version 113. The experimental flag #enable-experimental-web-platform-features preference needs to be set to enabled. Learn more.
  • ✨ You can see the decoded header and payload output in a large modal by clicking the resize button next to the copy button.
• A JWT encoder
  • The encoder takes as input JSON objects for the header and payload.
  • You can input a secret or private key to sign the token, a required step for generating the JWT.
  • We have improved communication about the different encodings and formats that secrets and private keys can have, respectively.
  • Secret: UTF-8 and base64url encoding.
  • Private Key: PEM or JWK formats.
  • The encoder now supports the encoding of unsecured JWTs.
  • ✨ Encoding and signing JWTs with the EdDSA (Ed25519) algorithm is now supported with the same constraints present in the decoder widget.
  • ✨ The encoder shows a warning when the alg claim is not equal to JWT.
• Both widgets offer better error messages so you can understand why your JWT encoding or decoding is not working and how to fix the issue.
• Both widgets have utility buttons on some of their inputs and outputs to help you perform common operations:
  • You can copy the content of some inputs and outputs using a button.
  • You can clear the content of inputs with a button click.
  • You can "push" the decoder outputs to be input in the encoder and vice versa through a "sync" button.
  • This is a feature where we need the most feedback, as the widget split is the biggest UI/UX change.
  • The current codebase was not handling errors coherently, and mixing encoding and decoding operations into a single flow was chaotic, leading to swallowed errors or confusing or non-responsive UX.
• You can choose an option to sync the decoder and encoder widgets.
  • The outputs of the decoder become the inputs of the encoder and vice versa.
  • Errors in the decoder create errors in the encoder and vice versa.
  • This behavior is somewhat similar to what jwt.io v1 does today but it introduces a clear separation layer between decoder and encoder operations to better understand what is triggering an error with the JWT to troubleshoot it more effectively.

Site architecture

• Perhaps the most important architectural change is migrating the code base from JavaScript with Pug and Express to Next.js with TypeScript.
  • This new stack gave us a multiplier effect to engineer a better UX and underlying JWT-related services.
  • This new stack will help us iterate faster through the application, address feedback faster, and grow its feature set.
• The query parameter used to filter libraries has been updated from ?language= to ?filter=.
  • Query parameter values have been updated to use safe URL characters.
    • For example, the value for kdb+/Q has been changed to kdb-q.
    • Old query parameters and values are still supported.
• We have migrated from using URL query parameters to preload JWTs into the JWT decoder to URL fragments.
  • The only support fragment is #token=.
  • Any other legacy query parameter will redirect to that fragment.
• We crafted the site to support internationalization as we plan to ship a localized version of JWT.io in Japanese next year.
• ✨ The site is now localized in Japanese.

Design

• The site now supports a dark and light theme.
• The hero banner and JWT warning message are much more compact and can be minimized to offer a more streamlined UI suitable for a developer tool.
  • We'd love for you to use JWT.io as much as you need. After a few times, or even after one time, you don't need to stare at the same FYI and warnings about copy-pasting JWTs around the web.
• Pickers allow you to select the encoding format for the secret and the format for the private/public key.
  • This allows us to provide a better user experience and more insightful error messages.
  • Labels around the pickers provide you with a better context of what it does.
• ✨ By default, the site selects your theme based on your system's theme preference.
  • However, if you want to use another theme, the site will remember your preference.

User Experience

• The site remembers your preferences using cookies.
  • Once you minimize a box or pick a decoded presentation, the site will look as such on your next visit or upon refresh.
• ✨ There are buttons to share feedback or report issues.
• ✨ The library cards now includes the library name as its title instead of the language/framework.

Content

• The introduction has a section that explains the difference between validating and verifying a JWT.
• The introduction has a section that explains the difference between decoding and encoding a JWT.

Deprecations

• Tooltips about JWT claims have been deprecated for the claims breakdown feature.
  • This change makes it easier for you to access this information when needed.
  • You can hide the description of claims in the decoded output table once you no longer need them.
• Tooltips for time-related claims (e.g., exp, nbf, iat, auth_time, and updated_at) that show the time in a readable format have been deprecated in favor of showing the time in the claims breakdown tab.
• The tooltip for weak secrets has been deprecated to show a detailed and helpful error message.
• The "Share JWT" feature has been deprecated.
• The "Tokens created" counter has been deprecated.
  • Should we bring this back? It's fun to look at but does not serve any functional purpose.

What's next?

• Top priority: Improve accessibility and keyboard navigation (WIP).
• We need to define a process to manage JWT libraries on the directory page.
  • When should we remove a library?
  • We could reflect helpful information to end-users, such as if a repo connected to the library was archived or if it's showing unmaintained signs.
    • See this helpful report made by snyff.
• I'd like to bring support to the site for encrypted JWTs. Is this something you'd be interested in using directly on the site so we can invest time and resources in it?
• Would you be okay if the website repo were to become private while a repo to submit JWT libraries remains public?
  • If you scroll to the footer of both jwt.io v1 and v2, you'll notice that we have built several other tools to help developers with identity-related tasks.
  • I have a vision and mission to update and revamp these other tools and connect them via an "app picker" similar to what Google Chrome offers for Google apps; however, they are a mix of private and public repos. Having them all in a single mono-repo would help accelerate the design and engineering process, but that repo would likely need to be private.

Thank you!

We appreciate your usage of jwt.io and all the feedback we have received throughout the years and recently. Working on jwt.io has been the highlight of my time at Auth0 and Okta. I hope that you get to love using this tool as much as we loved building it for you.

[imcarlosguerrero]

The UI looks pretty good, however I found that in dark mode when you'll select an algorithm, the contrast between the font and the background is too low as it's light gray over white, this problem seems to be present in other dropdown menus in the site.

I also think it'd be good to allow EdDSA (Ed25519, Ed448) as valid algorithms as seen here.

Someone have previously expressed interest in this feature, as seen in this community forum thread from two years ago.

[DanOnCall]

@imcarlosguerrero Thanks so much for your feedback and reporting this issue. To help me troubleshoot, do you mind sharing what OS and browser you are using, please?

I suspect that perhaps your OS theme is light as that could make the browser use light-themed colors for built-in browser UI elements like that select list. I was able to reproduce that in macOS + Chrome by setting up the OS theme to light; however, the text does show black instead:

[ElliotThiebaut]

I was able to reproduce the exact same behavior as @imcarlosguerrero on Windows with Chrome and Firefox but my OS is set to dark mode, as is my browsers.

Chrome user agent : Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36

Firefox user agent : Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:133.0) Gecko/20100101 Firefox/133.0

Hope that helps @DanOnCall !

[EdwardBlair]

Thank you for the effort you’ve invested in this.

As I write out this comment and consider potential UX enhancements, I noticed - without previously realising - many of them are already present on v1 jwt.io e.g. claims descriptions - v1 does this with tooltips on hover.

The tabular claims breakdown is a great addition, I like this - I am a human not a JSON parser.

I’d imagine most users are primarily focused on decoding tokens rather than crafting them. It seems unlikely that someone wouldn’t already have a tool for creating tokens as part of their workflow or experimentation setup - whether it’s a REPL, scratch pad script, or a tool like Postman. While the separate encode/decode widgets do a good job of clearly splitting the two functions, I’m not sure they offer much practical value beyond that separation.

A common frustration I have with v1 jwt.io is that, for example, changing the key automatically updates the signature, leading to confusion (e.g., being trolled into thinking I had guessed the correct secret). A mechanism to prevent this kind of issue would be much-appreciated.

With all this in mind, a better UX would include a lock/unlock button on the decoded side to enable or disable editing, along with making the claims breakdown table editable. In both modes, the secrets would remain editable, but in locked mode, it would function purely for verification.

---

The hero banner and JWT warning message are much more compact and can be minimized to offer a more streamlined UI suitable for a developer tool

Awesome. That was the only annoyance for me, it nearly caused me (meaning Claude) to create my own JWT decoder. For sure anyone going to jwt.io likely already knows what a JWT is. Would be interesting to see your analytics on that if you can share.

If I had to nitpick. I assume the libraries page will get an overhaul too. Placing the library name as the header of each card will improve scanability and be a more natural flow. At default scale on my MBP either I can see the framework, or the library name, but not both at the same time. Grouping them by framework/language may be a better means of presentation.

(( Spaces over tabs. Indent width of 2. Light mode over dark mode. These are hills I will d*e on. So please default light mode, or query the browser settings, and get 3/3 🥲 ))

[greglearns]

My initial impression upon seeing the new version was "Whoa, this is confusing" -- not good.

The old UI had
"Encoded: paste a token here" <--- clear, and obvious what to do. One input box, so clear what to do.

The new UI has, on the right side:
GENERATE A JWT <--- huh? I don't want to generate one, I want to verify one???
JSON WEB TOKEN (JWT) ... (copy or X) <--- copy? or close?? what happens if I close it? huh? I just want to validate a token)
Valid JWT <--- in green (by the time I was seeing this, I was already feeling confused, so the green wasn't even clear what it meant).
Signature verified <--- in green (same)

My initial reaction was "Whaa?" What was I supposed to do?

NOTE: I had a negative reaction, but I'm appreciative of the work you do (and I'm assuming that you truly want to hear the negative reactions so that you can make a wonderful experience). Thank you!

[the-docta]

agreeing with @greglearns:

• also changing algorithm in the "upper" block will overwrite my pasted JWT by some generated one...
• "generate" feature is nicely available in the bottom part (JWT Encoding) => leave it there.
• Leave the upper - probably by far most frequented part - to be verify-only
  • start with a generated one
  • make clear that a different Token can be pasted

===
the JWT area (left of the upper part) allows paste.
To be able to paste, I have to click in an area that contains the current JWT, plus one line. Clicking outside will not place focus for pasting into the text area.

For below screenshot:

• clicking in the area marked green, then Ctrl-A Ctrl-V will paste
• clicking anywhere in the pink area then Ctrl-A will select the content of the web page, Ctrl-V will do nothing

[achapla]

Great work! 👍
The separation of the encoder and decoder is a smart decision.
I’d suggest displaying validation messages directly below the JWT input field for better user experience.

[rgmz]

• Tooltips for time-related claims (e.g., exp, nbf, iat, auth_time, and updated_at) that show the time in a readable format have been deprecated in favor of showing the time in the claims breakdown tab.

Hey @DanOnCall ,

I frequently use JWT.io to quickly check timestamp fields. Removing the tooltips introduces a tremendous amount of friction because (i) it increases the number of required clicks from 0->1, and (ii) the layout shifts between the JSON and Claims Breakdown tabs.

For example, after pasting a JWT the entire list of claims is in the viewport. The old design allowed me to quickly and precisely view the time by hovering over the claim.

In addition to the new design requiring clicking the "Claims Breakdown" tab, it also requires scrolling as the exp claim (and others) gets bumped below the viewport.

---

I also find the Claims Breakdown layour difficult to read because the box is cramped and the value is split across lines.

[k0rean-rand0m]

I appreciate the new interface design! The separation of encoder and decoder is particularly well thought out. When I was first learning about JWT, having both encoding and decoding functions in a single field was somewhat confusing, so this separation makes the tool more intuitive.

However, I'd like to point out two usability concerns:

1. Text Selection Issue: When clicking on an empty area within the textbox, it doesn't focus as expected. This leads to accidentally selecting the entire website instead of the textbox content when using Cmd+A, as previously noted by @the-docta.

2. JWT Persistence: Currently, the JWK (Public Key) resets after pasting a new JWT. This creates additional friction when working with multiple JWTs, especially when needing to validate several tokens in succession.

[DanOnCall]

Thanks all for this incredible constructive feedback, which is helping validate some action items we wanted to implement based on user need and feedback.
We'll share the update to the beta after the holiday but JWT Elves have already been hard at work
🧝‍♂️ 💻

We want to build software that y'all love to use :) I am eager to get to that point! Thanks for using jwt.io and happy holidays!

[matteokov]

The new design looks excellent. Thank you for your great work.

One small thing from my side: maybe using the X icon is slightly confusing. Usually, I would use the X icon to close an alert or popup, not to clear data. Probably eraser icon would fit a little bit better.

[Aareksio]

I have been using jwt.io as go-to tool to decode JWTs over the years. On the first visit to new website, it is... unusable.

Not because of bad UI. It simply does not work with the token in my clipboard. It is signed with EdDSA. And the tool refuses to read it. Despite payload part being the same base64 encoded json as any other token. Please make it work :)

As a foreword, I never scrolled past the debugger, so the feedback is just about the homepage. The comment is about the product with the goal of making it the best possible, please do not take anything personally. There are two perspectives on jwt.io I have: (1) it is a tool to quickly check payload of a token, perhaps fiddle with it a bit, (2) it is a website I can send to new developers so they learn what a JWT is. Aside from plainly not working, there are two major issues with new design.

First issue is the identity crisis of the hero section. New page seems undecided whether it wants to focus 100% on the debugger, or retain some of the informational value of the old page. I love the old hero section, in two sentences, it provides condensed explanation on what JWT is and what the tool is about. It also has a clear path forward: click CTA or scroll down for debugger. And on subsequent visit the debugger is neatly visible due to different color background. New page ditches this state-of-the-art hierarchy for... alerts? I assure you, ain't nobody reading that. Yet they are the most contrasting elements on the page.

Second issue is the lack of visual guidance on different JWT parts. Old website done great job of distinguishing the header, payload and signature with different colors, both in the JWT and decoder components. It worked magic to demystify the weird token string. With new website, the colors are at best confusing - green header is the same color as "Valid JWT" above, blue signature is the same color as active tab on the right.

The look itself is a matter of taste, but there are still small improvements that could be made to better the experience. As the app seems to be a dev-lead project, I recommend a quick read on hierarchy and typography, for example relevant chapters of very approachable Refactoring UI from the creator of tailwind, written long before tailwind became cool.

[xlab]

Cookie nag screen definitely sucks. It has to be subtle, not block access to whole site.
Also, why even cookies?

[DanOnCall]

Thanks again for the feedback and I'll be replying to each individually as we took each feedback post and turned it into tickets to work on :)

[DanOnCall]

@imcarlosguerrero We have fixed the issue with the color of the select option lists by implementing a custom select element. Other feedback also validated an action item we had to make it much clearer that the role of the algorithm picker is to generate an example and nothing else. For that reason, that picker is now stashed within a small widget that has as call-to-action to generate a JWT example.

I received confirmation from QA that the custom select component work well on Windows.

Thanks for reporting this bug and please let me know if it has been resolved satisfactorily.

(We owe you the EdDSA implementation and I will mark it as an item for future implementation. I agree it's important to add support for them 🙏 )