A token is
a claim.
Your API checks it.

02 · Choose the right credential

🗝️ API keys, tokens, cookies — what's the difference?

Each credential has a different owner, audience and lifetime. Most "our auth is weird" problems come from using one where another belongs — an ID token sent to an API, a refresh token sent everywhere, an API key shipped in a mobile app.

03 · Take one apart

🔬 JWT structure: header.payload.signature

A signed JWT (technically a JWS in compact serialization) is three Base64URL-encoded segments joined by dots. Base64URL is Base64 with - and _ in place of + and /, and no = padding — so the token is safe in headers and URLs. If the encoding itself is new to you, read What is Base64? first.

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
.eyJpc3MiOiJodHRwczovL2F1dGguZXhhbXBsZS5jb20iLCJzdWIiOiJ1c2VyLTEwNDIiLCJhdWQiOiJvcmRlcnMtYXBpIiwiZXhwIjoxNzkwMDAwMDAwLCJpYXQiOjE3ODk5OTkxMDAsInNjb3BlIjoib3JkZXJzLnJlYWQifQ
.wEBOIaIbyB-hsgq_K-m2us0umpzmgFWeWlTla9aI2OE

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

// payload
{
  "iss":   "https://auth.example.com",
  "sub":   "user-1042",
  "aud":   "orders-api",
  "exp":   1790000000,   // 2026-09-21 14:13:20 UTC
  "iat":   1789999100,   // 15 minutes earlier
  "scope": "orders.read"
}

// signature
HMAC-SHA256( base64url(header) + "." + base64url(payload), secret )

Paste that token into the JWT Decoder and you'll get exactly the JSON above — without any key. That is the single most important fact about JWTs:

04 · Read the payload

🏷️ Standard JWT claims explained

RFC 7519 registers seven short claim names. None are mandatory in the spec, but a sane access token uses almost all of them — and your API should check the ones marked below.

Beyond those, you'll meet common non-registered claims such as scope (space-separated permissions, e.g. "orders.read orders.write"), roles, azp/client_id (which app requested it), tid (tenant) and sid (session). Their meaning is defined by your identity provider, not the JWT spec.

05 · Who holds which key

✍️ Signing: HS256 vs RS256 vs ES256

The alg header names the algorithm, but the real decision is who needs to verify tokens, and should they also be able to create them?

💡 Need a strong random HS256 secret or a test API key? The Token Generator and Password Generator produce them in your browser. In production, keep secrets in a vault or secret manager, never in the repo.

06 · The server's job

🛡️ JWT validation checklist

Every protected request, in this order. A mature library does most of it for you — if you configure it. Defaults vary, and "it decoded fine" is not a check.

1. 📨 Extract it strictly

   Read only Authorization: Bearer <token> (or your one agreed cookie). Reject tokens in query strings — URLs end up in logs, browser history and Referer headers.

2. 🔤 Check the algorithm against an allow-list

   Accept only what your issuer uses, e.g. RS256. Reject none always, and never switch key type based on the header.

3. 🔑 Verify the signature with a trusted key

   The key comes from your configuration or your issuer's JWKS endpoint — never from the token itself (ignore embedded jku/x5u/jwk headers unless they point at a URL you already trust).

4. ⏰ Check exp and nbf with small clock skew

   Allow 30–60 seconds for clock drift between servers. Note that ASP.NET Core's default ClockSkew is five minutes — a 5-minute token then effectively lives ten.

5. 🎯 Match iss and aud exactly

   The issuer must be one you trust; the audience must include this API. Skipping aud means a token minted for some other API on the same identity provider works on yours.

6. 🚦 Then authorize

   A valid token only proves who's calling. Now check scopes, roles, tenant and — the one most often forgotten — whether sub actually owns the resource in the URL. Return 403 when it doesn't.

07 · Paste-able examples

💻 Sending and verifying tokens in code

📮 Authorization header formats

The Authorization header is <scheme> <credentials>. The scheme tells the server how to read the rest. Build any of these without typos using the Authorization Header Generator.

⌨️ curl

# call a protected API with a bearer token
curl -H "Authorization: Bearer $ACCESS_TOKEN" \
     https://api.example.com/api/orders/1042

# service-to-service: get a token with the client credentials grant
curl -u "$CLIENT_ID:$CLIENT_SECRET" \
     -d grant_type=client_credentials -d scope=orders.read \
     https://auth.example.com/oauth2/token

# API key in a custom header
curl -H "X-API-Key: $API_KEY" https://api.example.com/v1/status

# see the 401 + WWW-Authenticate response when it fails
curl -i https://api.example.com/api/orders/1042

🟣 ASP.NET Core 8 — JwtBearer

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;

builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        // Authority → discovers the issuer's signing keys (JWKS) automatically
        options.Authority = "https://auth.example.com/";
        options.Audience  = "orders-api";

        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer           = true,
            ValidIssuer              = "https://auth.example.com/",
            ValidateAudience         = true,
            ValidateLifetime         = true,
            ValidateIssuerSigningKey = true,
            ValidAlgorithms          = new[] { SecurityAlgorithms.RsaSha256 },
            ClockSkew                = TimeSpan.FromSeconds(30)  // default is 5 min
        };
    });

builder.Services.AddAuthorization(o =>
    o.AddPolicy("orders.read", p => p.RequireAssertion(ctx =>
        (ctx.User.FindFirst("scope")?.Value ?? "")
            .Split(' ').Contains("orders.read"))));

var app = builder.Build();
app.UseAuthentication();   // order matters: authenticate first…
app.UseAuthorization();    // …then authorize

app.MapGet("/api/orders/{id}", (int id) => Results.Ok(new { id }))
   .RequireAuthorization("orders.read");

💡 Issuing your own HS256 tokens instead of using an identity provider? Drop Authority, set IssuerSigningKey = new SymmetricSecurityKey(keyBytes) from configuration, and change ValidAlgorithms to SecurityAlgorithms.HmacSha256.

🟢 Node.js — jsonwebtoken

import jwt from "jsonwebtoken";

export function requireAuth(req, res, next) {
  const [scheme, token] = (req.headers.authorization ?? "").split(" ");
  if (scheme !== "Bearer" || !token) {
    return res.status(401).set("WWW-Authenticate", "Bearer").end();
  }
  try {
    req.user = jwt.verify(token, PUBLIC_KEY_PEM, {
      algorithms: ["RS256"],               // allow-list — never omit
      issuer: "https://auth.example.com/",
      audience: "orders-api",
      clockTolerance: 30,                  // seconds
    });
    return next();
  } catch {
    return res.status(401).set("WWW-Authenticate", "Bearer").end();
  }
}

💡 jwt.decode() in the same library does no verification — it's for debugging only. For JWKS key fetching and rotation, pair it with jwks-rsa, or use the jose library's createRemoteJWKSet.

08 · Where the browser keeps it

🍪 Storing tokens in browsers: cookie vs localStorage

There's no perfectly safe place in a browser. The honest question is which attack you'd rather defend against: XSS (malicious script in your page) or CSRF (another site making your browser send requests).

09 · Refresh, logout, revoke

🔄 Refresh token rotation and the limits of stateless JWTs

Apps that keep you signed in for weeks aren't using one long-lived token. They pair a short-lived access token (minutes) with a protected refresh token that's only ever sent to the authorization server.

1. 🔓 Sign in once

   Password, passkey or external identity provider. The client receives an access token and a refresh token.

2. 📡 Call APIs with the access token

   Until it expires — the API answers 401, or the client refreshes a little before exp.

3. ♻️ Refresh — and rotate

   Each refresh returns a new refresh token and invalidates the old one. If an old refresh token is ever presented again, someone copied it: revoke the whole token family and force sign-in.

4. ⏳ Cap the session

   Use a sliding window for activity and an absolute maximum (say 30 days) so a session can't silently live forever.

🚪 Why "logout" doesn't kill a JWT

A self-contained JWT is valid until exp because the API never asks anyone. Logout clears the client and revokes the refresh token — but an access token already copied somewhere keeps working until it expires. Your options, from cheapest to most thorough:

✅ Ship-it checklist

• ✅ HTTPS everywhere; tokens never in URLs or logs
• ✅ Algorithm allow-list configured; none impossible
• ✅ iss, aud, exp, nbf validated, clock skew ≤ 60 s
• ✅ Scopes and resource ownership checked after authentication
• ✅ Access tokens short-lived; refresh tokens rotated with reuse detection
• ✅ Browser tokens in HttpOnly cookies or a BFF, with CSRF protection
• ✅ Signing keys rotatable via kid / JWKS without downtime
• ✅ A real answer to "how do we log a user out of every device?"