REST API JWT Tokens

A REST API keeps no memory of earlier requests, so each request must prove who is calling. A JSON Web Token, or JWT, solves this problem. The server issues a signed token after login, and the client attaches it to every later request.

The Concert Wristband Picture

At a music festival, staff check your ticket once at the gate and fasten a wristband to your arm. Every guard inside reads the wristband and lets you through without calling the ticket office. A JWT works like that wristband. The login server checks credentials once, and every other service trusts the signed token.

Anatomy of a JWT

A JWT holds three parts separated by dots.

xxxxx.yyyyy.zzzzz
  │      │      │
Header Payload Signature

Header

The header names the signing algorithm and the token type.

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

Payload

The payload carries claims, which are facts about the user and the token.

{
  "sub": "user-4821",
  "name": "Meera",
  "role": "editor",
  "iat": 1767225600,
  "exp": 1767229200
}

Claim	Meaning
sub	Subject, the user id
iss	Issuer, the server that created the token
aud	Audience, the API that should accept it
iat	Time of issue
exp	Expiry time

Signature

The server signs the encoded header and payload with a secret key. Any change to the token breaks the signature, so tampering shows up at once.

The Login and Request Flow

Client ── 1. POST /login (email, password) ──→ Auth Server
Client ←── 2. JWT ───────────────────────────── Auth Server
Client ── 3. GET /orders
          Authorization: Bearer eyJhbGci... ──→ API Server
                                                 │ verifies signature
                                                 │ checks exp, aud
Client ←── 4. 200 OK + data ──────────────────── API Server

Signing Methods

HS256

One shared secret signs and verifies tokens. This method suits a single application where one server does both jobs.

RS256

A private key signs tokens, and a public key verifies them. Many services can check tokens with the public key, and only the auth server holds the private key. Larger systems prefer this method.

Access Tokens and Refresh Tokens

Short life limits damage when a token leaks. Access tokens usually expire in 5 to 15 minutes. A refresh token lives longer, often days, and exists only to request new access tokens. The client sends the refresh token to the auth server, never to the regular API.

Access token expires
        │
        ▼
Client sends refresh token ──→ Auth Server
        │
        ▼
New access token issued ──→ Client continues

What the Server Must Verify

• The signature matches the expected key and algorithm.
• The exp time lies in the future.
• The iss value matches the trusted issuer.
• The aud value names this API.
• The claims grant permission for the requested action.

Storage and Revocation

Browsers store tokens in memory or in HttpOnly cookies, which scripts cannot read. Mobile apps use the secure storage that the operating system provides. A signed JWT stays valid until it expires, so revoking one early needs extra tools. Teams keep a short denylist of cancelled token ids or rotate signing keys after a breach.

Common Mistakes

Treating the Payload as Secret

Base64 encoding is not encryption. Anyone holding a token can read the payload. Keep passwords, card numbers, and private data out of it.

Long Expiry Times

A token valid for a month gives a thief a month of access. Keep access tokens short and rely on refresh tokens.

Accepting the none Algorithm

Servers must pin the allowed algorithms. A library that accepts unsigned tokens lets anyone forge identity.

Skipping HTTPS

A token sent over plain HTTP travels in readable form. Use HTTPS for every call.