Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 38 ยท Authentication and Sessions Testing

JWT and API Token Testing

Learn how JSON Web Tokens are structured, what to check when you test them in Burp (algorithm, expiry, claims, signature), and how to inspect a token with Python.

Modern APIs often replace cookie sessions with tokens, and the most common token is the JSON Web Token (JWT). A JWT carries claims about the user (sub, role, exp) and is signed so the server can trust it without a database lookup. That convenience is also its risk: a misconfigured server may trust a token it should reject. In this lesson you learn the structure of a JWT, what a tester checks, and how to inspect a token safely.

Burp is a desktop tool, so its screens are labelled example output. The runnable block decodes a token offline with the Python standard library. Test only systems you are authorised to test, with tokens issued to your own test accounts.

Anatomy of a JWT

A JWT is three Base64URL-encoded parts joined by dots:

TEXT
header.payload.signature
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsInJvbGUiOiJ1c2VyIiwiZXhwIjoxNzMyMDAwMDAwfQ.<signature>
Part Content Example decoded
Header Algorithm and type {"alg":"HS256","typ":"JWT"}
Payload Claims {"sub":"42","role":"user","exp":1732000000}
Signature MAC or digital signature over header.payload binary

Two points surprise beginners. First, the payload is encoded, not encrypted: anyone can read it. Never put secrets in it. Second, only the signature protects integrity, so everything depends on the server verifying it correctly.

Registered claims worth checking

  • exp (expiry), nbf (not before), iat (issued at)
  • iss (issuer), aud (audience), sub (subject)
  • jti (token ID, used for revocation)

Inspect a token offline

This block builds a token locally with a test secret and decodes it, showing exactly what Burp's Inspector shows. Everything is in memory.

Python Build and decode a JWT with the standard library (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In Burp you would see the same decoded parts by selecting the token in a request and looking at the Inspector panel, or by using a JWT extension from the BApp Store (see extensions).

What to test

A tester asks whether the server verifies everything it should. Each item below is a check, performed on your own test token against an authorised test system.

  1. Signature validation: does the server reject a token whose payload was edited but whose signature was not recomputed? If the edited token (for instance role changed) is accepted, the server is not verifying at all.
  2. Algorithm handling: does the server insist on the algorithm it expects? Historic bugs include accepting "alg":"none" (an unsigned token) or letting a client switch an RSA public-key algorithm to HMAC, so that the public key is used as the HMAC secret. Modern libraries refuse these, but old or hand-rolled code may not.
  3. Expiry: is exp enforced? Send an expired token. Is the lifetime sensible (minutes for access tokens)?
  4. Audience and issuer: does the API accept tokens meant for another service (aud)?
  5. Key strength: is an HMAC secret short or guessable? A weak shared secret can be recovered offline from one token. Checking this belongs on your own lab token, and the fix is a long random secret or asymmetric keys.
  6. Header injection: do kid, jku or x5u header fields let the client point the server at its own key or file? These header parameters must be validated against a fixed allow-list.
  7. Revocation: after logout or password change, is the old token still accepted until it expires?
  8. Storage and transport: is the token in localStorage (readable by any script on an XSS) or in an HttpOnly cookie? Is it ever in a URL, which leaks through logs and referrers?

A defensive verifier

Here is what correct verification looks like: check the algorithm against an allow-list, check the signature in constant time, then check the claims. The tests show a valid token passing and tampered or expired ones failing.

Python A strict verifier rejects tampering (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Read the four results: only the untouched token passes. When a real API behaves like a worse verifier, that is a finding.

Using Burp for token testing

  • Repeater: send the request with the modified test token and compare against the normal response (status, body length).
  • Inspector: edit decoded claims inline for your own test token.
  • Intruder: in an authorised test, replay with a small list of expiry or audience variants.
  • Logger / Extensions: use a JWT-aware extension to decode, edit and re-sign tokens with a key you own.

Also consider opaque tokens (random strings looked up server side): analyse them with Sequencer, and API keys: check that they are scoped, rotatable, and not exposed in client code.

Reporting tokens issues

Describe the observed behaviour, the exact claim or header you changed, the response proving it was accepted, and the impact (for example privilege escalation if role is trusted). The fix is usually "use a maintained library, pin the algorithm, validate all claims, short expiry, rotate keys". See writing findings.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Is the payload of a normal signed JWT encrypted?

    A signed JWT (JWS) is encoded, not encrypted; the signature gives integrity, not secrecy.
  2. 2. A server accepts a JWT whose role claim was edited without re-signing. What is wrong?

    A correct server rejects any token whose signature does not match its contents.
  3. 3. Why should the server pin the expected algorithm?

    Trusting the token's own alg field enabled historic bypasses such as none and key confusion.
  4. 4. Where is storing a JWT riskier?

    XSS can read localStorage, while HttpOnly cookies are hidden from scripts.
  5. 5. Which claim limits how long a token is valid?

    exp is the expiry time; the server must enforce it.

Summary

  • A JWT is header, payload and signature, each Base64URL; the payload is readable by anyone.
  • Test signature verification, algorithm pinning, expiry, audience, key strength, header parameters and revocation.
  • A strict verifier checks the allow-listed algorithm, the signature in constant time, then the claims.
  • Use Burp's Inspector, Repeater and JWT extensions on your own test tokens against authorised systems.
  • Report with the exact change, proof and a library-based fix.

Next: SQL injection testing workflow