Add clerk jwt debugger

[jeremy-clerk]

Important

🔎 Preview (for some reason bugs out): https://clerk-git-jeremy-add-clerk-jwt-debugger.clerkstage.dev/docs/pr/jeremy-add-clerk-jwt-debugger/guides/development/troubleshooting/jwt-decoder

To preview locally, pull this PR, and the clerk/clerk PR together to view locally.

This PR adds a Clerk JWT debugging tool

Checklist

• I have clicked on "Files changed" and performed a thorough self-review
• I have added the "deploy-preview" label and added the preview link(s) to this PR description
• All existing checks pass

[github-actions]

Hey, here’s your docs preview: https://clerk.com/docs/pr/1816

[github-actions]

⚠️ TypeDoc files detected in this PR

This PR modifies files in the 'clerk-typedoc/' folder. These files are auto-generated from the clerk/javascript repository and should not be edited directly.

To make changes to TypeDoc documentation:

1. 🔄 Make your changes in the appropriate files in the clerk/javascript repository.
2. 🚀 The TypeDoc documentation will be pulled through to this repository via a CI action.

Thanks for contributing! 🙏

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
clerk-docs	Ready	Preview	Nov 21, 2025 10:32pm

[SarahSoutoul]

How would I be able to test this? I'm getting this locally (even when on your clerk PR branch), and wondering if there is a specific setup I need to follow here:

[alexisintech]

woooo!! this is super exciting, and its looking really awesome. everything seems to be working as expected!

a few things:

the title of the page is "Decode Clerk JWTs" - is it Clerk specific? or can it decode any JWT?

I have some issues with the design here. The flow doesn't feel intuitive. I think that the text beneath the "JWT" box should actually be above it, maybe we can do a quiz callout where it says "How do I get my Clerk session token?" and the user can expand the callout to get the answer. or maybe we can put a hoverable next to the session token dropdown like in the screenshot:

The "Header" box can be less height - similar to how jwt.io does theirs. I think it takes up too much of the fold, when the focus is usually the payload. Also, following jwt.io's suit, I think the public key box can use more explanation (they signal clearly that its optional. they mention that its the public key used to sign the JWT. they show what format it is, pem vs jwk)

[jeremy-clerk]

woooo!! this is super exciting, and its looking really awesome. everything seems to be working as expected!

a few things:

the title of the page is "Decode Clerk JWTs" - is it Clerk specific? or can it decode any JWT?

Technically any RS256 JWT but if we wanted to decode any JWT it would take a bit more work to support all the algorithms. So I just wanted to start with "Clerk JWTs" to set the expectation that it will work for sure with Clerk JWTs. Part of this is that I'm not using any 3rd party libraries for the JWT decoding/verification to make sure it's "all Clerk" - so each has to be implemented manually.

I have some issues with the design here. The flow doesn't feel intuitive. I think that the text beneath the "JWT" box should actually be above it, maybe we can do a quiz callout where it says "How do I get my Clerk session token?" and the user can expand the callout to get the answer.

Yeah the original design didn't call for the text at all, but I felt it was kinda empty or confusing without it. So I added it in (and copied from the postman section). I can move it up, I don't have any strong opinions on it tbh.

The "Header" box can be less height - similar to how jwt.io does theirs. I think it takes up too much of the fold, when the focus is usually the payload.

Easy enough. I just used the same box so I'll modify the height for the header.

Also, following jwt.io's suit, I think the public key box can use more explanation (they signal clearly that its optional. they mention that its the public key used to sign the JWT. they show what format it is, pem vs jwk)

The default on jwt.io's page is the secret which we don't have here since we're just decoding/verifying via a public key, but we can add some text. The flow is:

• If you paste in a Clerk JWT (or select a cookie) we will automatically grab the key from JWKS endpoint to verify the JWT.
• If you want to sign a new token, we generate an ephemeral key pair that stays in the browser to sign the token and then verify the signature with the public key. I didn't want to show the private key as I didn't want anyone to try and use the private key for something or think it applied to their Clerk app somehow.

[jeremy-clerk]

How would I be able to test this? I'm getting this locally (even when on your clerk PR branch), and wondering if there is a specific setup I need to follow here:

@SarahSoutoul - I have no idea, I would guess something isn't installed or linked, happy to pair with you when you have a moment to sort it out though!

[jeremy-clerk]

@alexisintech I also wanted to put something somewhere about "How this works" to clarify for users but I didn't have any good ideas of where/what it should look like. Curious if you had any good ideas or insight into that.

[alexisintech]

@alexisintech I also wanted to put something somewhere about "How this works" to clarify for users but I didn't have any good ideas of where/what it should look like. Curious if you had any good ideas or insight into that.

I think above the "Next steps" section would be fine!

[jeremy-clerk]

Added popover for 'How do I get a Clerk session token?'

[jeremy-clerk]

Added some more info on the bottom

[alexisintech]

Added popover for 'How do I get a Clerk session token?'

it feels like it should be hoverable.
if you want it to be clickable instead of hoverable, i'd update the design so it looks more like a button (indicating clickability).

[alexisintech]

Added some more info on the bottom

i feel like this should go at the top! tagging in @SarahSoutoul for her suggestions / opinion

[jeremy-clerk]

Added popover for 'How do I get a Clerk session token?'

it feels like it should be hoverable.

if you want it to be clickable instead of hoverable, i'd update the design so it looks more like a button (indicating clickability).

I fought with trying to get the underline for a while and gave up 😂

The only reason I opted for clickable was so you don't have that annoying thing where you're trying to interact with it and it goes away

[SarahSoutoul]

Added some more info on the bottom

i feel like this should go at the top! tagging in @SarahSoutoul for her suggestions / opinion

Yeah should def be at the top! @alexisintech @jeremy-clerk