When an API returns a 401, a JWT decoder can show what the token contains, but decoding is only the first step. This guide provides a reusable workflow for inspecting JWT structure, checking claims, verifying signatures, isolating authentication errors, and choosing safer tools without treating an unverified token as trusted data.
Overview
A JSON Web Token (JWT) is commonly represented as three Base64URL-encoded parts separated by periods:
header.payload.signature
- Header: Usually identifies the token type and signing algorithm, such as
algandtyp. A key identifier such askidmay also appear. - Payload: Contains claims, including application-specific data and registered claims such as
iss,sub,aud,exp,nbf, andiat. - Signature: Allows a verifier to check whether the header and payload were signed with an expected key and algorithm.
Decoding a JWT means Base64URL-decoding the header and payload. It does not prove that the token was issued by your identity provider, has not been altered, or should be accepted by your application. Validation requires signature verification and claim checks performed by trusted application code or a suitable security library.
Before troubleshooting, capture the complete request context: the HTTP status, response body, endpoint, authorization scheme, token source, and the service that rejected the request. A token can be valid in isolation but rejected because it targets a different API, comes from the wrong issuer, or is sent in the wrong header format.
Choosing a JWT tool
| Tool type | Best use | Important limitation |
|---|---|---|
| Browser-based JWT decoder | Quickly inspect a non-sensitive development token | Do not paste production tokens or secrets into an unapproved third-party service |
| Command-line utility | Repeatable local decoding and scripting | Shell history, process output, or logs can expose the token |
| Application library | Signature verification and claim validation in real requests | Requires correct configuration, key handling, and error reporting |
| API client | Testing authorization headers and endpoint behavior | Saved environments and request collections may contain sensitive credentials |
For a fast inspection, use a local tool or a browser-based utility only with a deliberately non-sensitive token. For any trust decision, validate inside the same application stack that serves the protected endpoint. Your API testing workflow should separate request construction from authentication verification.
Checklist by scenario
Scenario 1: You need to decode a JWT
- Confirm that the value has the expected number of segments. A signed JWT usually has three. An encrypted JWT (JWE) has a different structure and cannot be inspected as an ordinary signed payload.
- Copy the token without the
Bearerprefix, surrounding quotes, or whitespace. - Decode the header and payload as Base64URL, not ordinary Base64. Padding may be omitted in JWT encoding.
- Parse both decoded sections as JSON and record the values of
alg,kid,iss,aud,sub,exp, andnbf. - Mark the result as inspection only. Never authorize a user based solely on decoded claims.
Scenario 2: The API returns 401 or 403
- Check that the request uses the expected scheme, commonly
Authorization: Bearer <token>. - Verify that the token is being sent to the correct environment and API host. Development, staging, and production often use different issuers or signing keys.
- Compare
isswith the issuer configured by the receiving service. - Compare
audwith the audience expected by that API. A token issued for a user-information endpoint may not be valid for a separate resource server. - Check
expandnbfagainst the verifier's clock. A small, explicitly configured clock-skew allowance may be appropriate, but it should not hide a substantially expired token. - Check permissions separately. A correctly authenticated token may still lack a required scope, role, or claim, producing a 403 or an application-specific authorization error.
Scenario 3: Signature verification fails
- Identify the algorithm in the header, but do not allow the token to choose an unrestricted set of algorithms. The verifier should use an explicit allowlist appropriate to the deployment.
- Confirm that the verifier has the right key type. Symmetric algorithms use a shared secret; asymmetric algorithms use a public key corresponding to the issuer's private signing key.
- Resolve the correct key using the configured issuer and, where applicable, the token's
kid. A rotated key, stale key cache, or wrong tenant can cause a valid token to fail verification. - Check whether the token was copied, truncated, URL-decoded incorrectly, or altered by a proxy or logging workflow.
- Inspect library errors in a controlled environment, but return generic authentication errors to clients rather than revealing key or verification details.
Scenario 4: Refresh-token handling is involved
- Determine whether the failing value is an access token or a refresh token. They may have different audiences, lifetimes, storage rules, and accepted endpoints.
- Do not send a refresh token to an ordinary resource API unless the identity system explicitly requires it.
- When an access token expires, use the intended refresh flow rather than extending or editing the payload.
- Prevent refresh loops: if refresh fails, clear the session or require sign-in instead of retrying every request indefinitely.
What to double-check
Use this token-inspection template for a controlled debugging note. Do not paste the full token into tickets, chat, screenshots, or issue trackers.
Environment: development | staging | production
Endpoint:
HTTP status:
Issuer (iss):
Audience (aud):
Subject (sub): redacted identifier
Key ID (kid):
Algorithm (alg):
Issued at (iat):
Not before (nbf):
Expires at (exp):
Expected issuer:
Expected audience:
Expected algorithm:
Verification result:
Authorization result:
Check timestamps as numeric date values and convert them consistently when comparing logs. Confirm that the application and identity provider have synchronized clocks. Also check whether a gateway, reverse proxy, or middleware removes the Authorization header before the request reaches the application.
Validation should normally cover the signature, permitted algorithm, issuer, audience, expiration, and not-before time. Add checks for scopes, roles, token type, tenant, or client ID when your application depends on them. Treat optional claims as optional only if the authorization design genuinely permits their absence.
Keep authentication configuration aligned with the API contract. If an endpoint's required scopes, audience, or security scheme are unclear, document them in your OpenAPI workflow so request tests and implementation can be compared.
Common mistakes
- Confusing decoding with validation: Anyone who has a token can usually read its unsigned contents. Readability is not authenticity.
- Trusting header values: The
algandkidfields are inputs to validate, not instructions to accept blindly. - Checking only expiration: An unexpired token can still have the wrong issuer, audience, signature, tenant, or permissions.
- Using the wrong key: Similar environments or identity-provider tenants may expose different signing keys.
- Logging credentials: Full access and refresh tokens should not appear in application logs, analytics events, support tickets, or shell history.
- Editing the payload: Changing a claim invalidates the signature. Re-signing with an unapproved key does not make the token trusted.
- Overexposing error details: Detailed verification failures are useful during local debugging but can disclose implementation information in production responses.
- Ignoring dependency configuration: A secure library can still be used unsafely if verification is disabled, issuer checks are omitted, or key retrieval is configured incorrectly. Include authentication settings in code review and local quality gates; the Git hooks guide offers a broader approach to repeatable checks.
When to revisit
Return to this checklist whenever authentication behavior changes or a previously working request starts failing. In particular, revisit it when you integrate a new identity provider, add a tenant, change an API audience, rotate signing keys, alter token lifetimes, introduce refresh-token rotation, upgrade an authentication library, or move traffic through a new proxy.
It is also worth reviewing before a release that changes claims, scopes, roles, clock configuration, or error handling. Recheck browser-based JWT tools and local utilities before using them for sensitive debugging, because their supported algorithms, privacy behavior, and interfaces can change.
For the next incident, take these actions in order:
- Redact the token and record the endpoint, environment, status, and timestamp.
- Decode header and payload locally to inspect structure and claims.
- Compare issuer, audience, algorithm, key ID, and time claims with the service configuration.
- Verify the signature and claims using the application's trusted library and configured keys.
- Test permissions after authentication succeeds, then document the root cause without retaining the credential.
This sequence keeps a JWT decoder in its proper role: a useful inspection tool within a broader, verifiable authentication workflow.