A JWT decoder online can quickly show why an API token is being rejected, but decoding is only inspection—not proof that a token is authentic. This guide provides a reusable checklist for safely separating a JWT into its header, payload, and signature, checking claims such as issuer, audience, expiration, and not-before, and verifying the signature with the correct key in a controlled developer workflow.
Overview
A JSON Web Token (JWT) is commonly represented as three Base64URL-encoded parts separated by periods:
header.payload.signature
The header describes the signing method and key identifier, the payload contains claims, and the signature is used to verify that the signed content has not been changed. A browser-based JWT decoder can decode the first two parts because they are encoded rather than encrypted. Anyone who receives a token may be able to read those claims.
That distinction is important during troubleshooting. A decoded payload may explain an authentication failure, but it should not automatically be trusted. An online JWT decoder is suitable for a deliberately created test token or a redacted sample. Avoid pasting production access tokens, refresh tokens, session credentials, or tokens containing personal or confidential data into an untrusted website. Prefer a local tool, a development environment, or your identity platform's approved diagnostic tooling when the token is sensitive.
For a useful investigation, record the symptom first. Is the API returning an HTTP 401 or 403 response? Does the failure occur only after a period of time, only on Windows, or only with one identity provider? The answer determines which token properties deserve attention.
Checklist by scenario
When the token is rejected immediately
- Confirm the token shape. A signed JWT normally has three non-empty segments. An encrypted JWT may have five segments and requires a different decryption workflow. Do not assume every dot-separated token can be inspected in the same way.
- Inspect the header. Note the
algvalue and, when present, thekidvalue. The algorithm selected by the token must be allowed by the API, and the key identifier must map to a compatible verification key. - Check the issuer and audience. Compare
isswith the API's configured issuer andaudwith the identifier expected by that API. A token can be correctly signed and still be intended for a different service. - Check the authorization header. Confirm that the request uses the expected scheme, typically
Authorization: Bearer <token>, without extra quotation marks, line breaks, or a duplicated prefix.
When the token worked and then stopped
- Read the time claims. Compare
exp(expiration) andnbf(not before) with the current UTC time. These values are commonly expressed as Unix time, meaning seconds from the Unix epoch. - Check clock differences. A machine with an incorrect system clock can reject a token that appears valid elsewhere. Compare the Windows host, API host, container, virtual machine, or identity service involved in the request.
- Look for key rotation. If the header's
kidno longer resolves to a currently available key, verification may fail after a signing-key change. Check how the API refreshes the issuer's published key set rather than copying a key permanently into configuration. - Compare environments. Development, staging, and production often use different issuers, audiences, keys, and tenant settings. Capture these values from the actual request path rather than relying on a familiar configuration file.
When claims look correct but authorization still fails
- Separate authentication from authorization. Successful signature validation establishes that the token is acceptable as a signed credential; it does not guarantee access to every endpoint.
- Inspect scopes and roles. The API may expect a particular scope claim, role format, permission name, or claim namespace. Compare the token with the endpoint's authorization requirements.
- Check the token type. An ID token is generally intended to describe an authenticated user to a client, while an access token is intended for a resource server. Use the token issued for the API being called.
- Review server logs safely. Correlate request IDs, issuer, audience, key ID, and validation error categories. Avoid logging complete bearer tokens.
When debugging a Windows application
Check the request generated by the application rather than only the token displayed in a development console. Browser developer tools, application logs, and an HTTP capture in a controlled environment can reveal whether the token is missing, stale, truncated, or sent to the wrong host. For localhost issues involving ports, hosts files, DNS, firewalls, IIS, or WSL, see Debugging Localhost on Windows. If the application uses WebView2, its profile and runtime behavior may also affect how authentication state is stored; the WebView2 troubleshooting guide provides related checks.
What to double-check
| Item | What to compare | Typical question |
|---|---|---|
alg | Token header and API allowlist | Is the API configured to accept this signing algorithm? |
kid | Header and issuer key set | Can the verifier locate the corresponding public key? |
iss | Token and API configuration | Was this token issued by the expected authority? |
aud | Token and resource identifier | Was it issued for this API rather than another client? |
exp/nbf | Claims and UTC time | Is the token currently within its valid time window? |
| Scopes and roles | Claims and endpoint policy | Does the caller have the permission this route requires? |
Use a decoder to inspect values, then use a verifier to establish authenticity. Signature verification requires the correct cryptographic material: a public key for an asymmetric algorithm or an appropriately protected shared secret for a symmetric algorithm. Never paste a production signing secret into an online tool. Verification should also enforce an expected algorithm and validate issuer, audience, time, and relevant application claims.
For .NET or PowerShell troubleshooting, keep the decoded output separate from application logs and redact the token before sharing a bug report. A safe report can include the algorithm, key ID, issuer, audience, claim names, time values, HTTP status, and validation error category without including the full credential.
Common mistakes
- Treating Base64URL decoding as decryption. Decoding reveals representation; it does not make the data confidential or prove who created it.
- Trusting claims before verification. An attacker can construct a payload with an administrator role. Do not use decoded claims for access decisions until the signature and validation rules have passed.
- Accepting whatever algorithm the token announces. The verifier should select an approved algorithm through configuration and policy, not blindly follow untrusted input.
- Ignoring audience. A valid token for one API or client may be inappropriate for another.
- Checking local time instead of UTC. JWT time claims are normally compared as absolute timestamps. Time-zone displays can make a valid value appear confusing.
- Logging bearer tokens. Full tokens in console output, build logs, crash reports, or tickets can become credentials. Log metadata and hashes only when that is appropriate for the investigation.
- Confusing a 401 with a 403. A 401 commonly indicates that authentication was absent or invalid, while a 403 can indicate that authentication succeeded but the caller lacks permission. The exact behavior depends on the application.
- Assuming a browser decoder verifies the token. Some tools offer verification, while others only parse the header and payload. Read the tool's behavior and use an approved local verifier for sensitive investigations.
If authentication debugging leads to a deployment or build problem rather than a token problem, keep the investigation separate. An MSBuild binary log can help isolate build failures, while Windows Event Viewer can help identify application or service errors. Avoid changing token validation settings merely to make an unrelated Windows failure disappear.
When to revisit
Return to this checklist whenever an identity provider, API gateway, authentication library, or signing-key configuration changes. It is especially useful during key rotation, tenant or environment migration, changes to scopes and roles, expiration-policy updates, and integration testing with a new identity provider. Recheck the workflow when a JWT decoder or verification tool changes its handling of local data, supported algorithms, or key input.
Before closing an incident, take these practical actions:
- Save a redacted token sample or only its non-sensitive metadata, never an active production credential.
- Record the issuer, audience, algorithm, key ID, time claims, response status, and environment.
- Reproduce the request with a newly issued development token if possible.
- Verify the signature locally or through an approved service using the expected key and algorithm.
- Confirm authorization separately by checking the required scopes, roles, or policies.
- Remove temporary verbose logging and rotate any credential that may have been exposed during debugging.
This approach makes a JWT decoder one part of a broader developer-tool workflow: useful for rapid inspection, but always followed by controlled verification and least-exposure handling of credentials.