JSON Web Tokens (JWT)

JSON Web Token (JWT) (pronounced "jot") is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

In the API world, JWTs are the most common format for Access Tokens and ID Tokens.

The Structure of a JWT

A JWT consists of three parts separated by dots (.):
Header.Payload.Signature

Example: eyJhbGciOiJIUzI1Ni... .eyJzdWIiOiIxMjM0NTY3ODkw... .SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

1. Header

Describes how the token is signed.

{
  "alg": "HS256",
  "typ": "JWT"
}

2. Payload (Claims)

Contains the data (claims). There are standard claims and custom claims.

{
  "sub": "1234567890",   // Subject (User ID)
  "name": "John Doe",
  "iat": 1516239022,     // Issued At
  "exp": 1516242622,     // Expiration Time
  "role": "admin"        // Custom claim
}

Note: This data is Base64Url encoded, NOT encrypted. Anyone who has the token can read this data. Do not put secrets here.

3. Signature

To create the signature part, you have to take the encoded header, the encoded payload, a secret, and the algorithm specified in the header, and sign that.

HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

The signature ensures that the token has not been altered.

How JWT Works in an API

Authentication: User logs in.

Creation: Server creates a JWT, signing it with a Secret Key (known only to the server).

Response: Server sends the JWT to the Client.

Storage: Client stores it (usually in localStorage or an HttpOnly cookie).

Request: For every subsequent request, the Client sends the JWT in the Authorization header:
Authorization: Bearer <token>

Verification: The Server receives the token. It recalculates the signature using its Secret Key.

If the signatures match -> The token is valid and hasn't been tampered with.

The server uses the data in the Payload (e.g., user_id) to process the request. No database lookup is needed to check the session!

Pros and Cons

Pros

Stateless: The server doesn't need to keep a session record in RAM or DB. Good for scalability.

Compact: Small enough to be sent in URLs, POST parameters, or HTTP headers.

Cross-Domain: Works well with CORS and mobile apps.

Cons

Revocation is Hard: Since the server doesn't track sessions, you can't easily "log out" a user server-side or ban a token before it expires. You often need a "blocklist" (restoring state) or short expiration times to mitigate this.

Size: Can get large if you put too much data in the claims.

Security Best Practices

Always use HTTPS: Or the token can be stolen in transit.

Short Expiration: Keep exp short (e.g., 15 min) and use Refresh Tokens.

Validate Algorithms: Ensure your server only accepts the algorithms you intend (e.g., prevent "none" algo attacks).

Key Takeaways

JWTs are self-contained statless tokens used for AuthN and AuthZ.

They are signed (tamper-proof) but encoded (readable by anyone), so never put secrets in the payload.

Always verify the signature before trusting the claims.

Next Step: Now that we know how to secure access, let's look at what attackers do when they find a crack. The OWASP API Security Top 10.

JSON Web Tokens (JWT)

The Structure of a JWT#

1. Header#

2. Payload (Claims)#

3. Signature#

How JWT Works in an API#

Pros and Cons#

Pros#

Cons#

Security Best Practices#

Key Takeaways#