Developer and API security
How to inspect a JWT without confusing decoding with verification
Read JWT headers and claims, interpret time fields, identify algorithm warnings, and understand why decoded content is not automatically trusted.
Document summary
A security-focused JWT inspection guide that separates readable payload data from signature verification and authorization decisions.
Key takeaways
- Anyone holding a JWT can usually decode its header and payload.
- A decoded token is not verified until its signature and claims are checked.
- Do not paste production tokens into tools that send content to a server.
Understand the three JWT sections
A common signed JWT contains a Base64URL-encoded header, payload, and signature separated by periods. Decoding the first two sections makes them readable but does not prove that they were issued by a trusted system.
| Section | Typical content | Trust level after decoding |
|---|---|---|
| Header | Token type, signing algorithm, key identifier | Untrusted until verification |
| Payload | Claims such as subject, issuer, audience, and timestamps | Untrusted until verification |
| Signature | Cryptographic proof over header and payload | Must be verified with the expected key and algorithm |
Separate decoding from verification
Decoding is only a representation change. An attacker can create a token with any header and payload. Verification checks the signature with a trusted key and must also enforce the expected issuer, audience, algorithm, and time rules.
Accept the role claim because the payload is readable.Verify signature, issuer, audience, algorithm, and time claims before using authorization data.Review registered and application-specific claims
Common claims include iss for issuer, sub for subject, aud for audience, exp for expiration, nbf for not-before time, and iat for issued-at time. Application-specific claims may carry roles or permissions.
A claim can be syntactically valid while still being wrong for the current application. Compare values with trusted configuration.
- Issuer matches the expected identity provider.
- Audience includes the current API or application.
- Subject is present when the workflow requires it.
- Permissions are interpreted only after verification.
Interpret time claims consistently
JWT NumericDate values are seconds since the Unix epoch. Check expiration and not-before values with a small, deliberate clock-skew allowance.
Tokens with missing or unreasonable timestamps may require rejection depending on the security policy.
| Claim | Meaning | Common check |
|---|---|---|
| exp | Expiration time | Current time must be earlier |
| nbf | Not valid before | Current time must be later |
| iat | Issued at | Should be plausible and not far in the future |
Protect tokens during inspection
JWT payloads can contain personal data, tenant identifiers, internal URLs, roles, or other sensitive details. Tokens may also grant access until they expire.
Prefer local browser inspection and use test tokens. Never place live tokens in documentation, screenshots, analytics, support tickets, or public issue trackers.
Use a complete verification checklist
- 1
Parse exactly the expected token structure.
- 2
Reject unapproved algorithms.
- 3
Select a trusted key using controlled configuration.
- 4
Verify the signature.
- 5
Validate issuer and audience.
- 6
Validate exp, nbf, and any required claims.
- 7
Apply authorization rules only after all checks pass.
