Signing algorithm guide

Choose the right algorithm for your architecture:

HS256 (HMAC-SHA256): fastest option. A single shared secret signs and verifies. All services that verify the token must know the secret, so this works best for single-service or tightly coupled architectures.
RS256 (RSA-SHA256): the private key signs; any holder of the public key can verify. Ideal for microservices - the auth service keeps the private key and publishes the public key at a JWKS endpoint. No secret distribution problem.
ES256 (ECDSA P-256): similar properties to RS256 but uses an elliptic curve key pair. Produces much smaller signatures (64 bytes vs ~256 bytes for RS256) with equivalent security.

Expiration best practices

Access tokens: short-lived, typically 15 minutes to 1 hour. Short expiry limits damage if a token is stolen.
Refresh tokens: longer-lived, typically 7–30 days. Used to issue new access tokens without requiring re-authentication.
Never issue access tokens without an exp claim - a non-expiring token is a permanent credential if leaked.
Clock skew between servers can cause premature rejection; build in 30–60 seconds of tolerance (leeway).

Standard claims reference

Claim	Full name	Description
`iss`	Issuer	Principal that issued the token (URL or identifier)
`sub`	Subject	User or entity the token refers to (user ID)
`aud`	Audience	Intended recipients; validated by receiving service
`exp`	Expiration	Unix timestamp after which token must be rejected
`nbf`	Not Before	Unix timestamp before which token must be rejected
`iat`	Issued At	Unix timestamp when the token was created
`jti`	JWT ID	Unique ID; used to prevent replay attacks

JWT Structure

A JWT consists of three Base64URL-encoded parts separated by dots: the header (algorithm and type), the payload (claims), and the signature. HS256 produces a 256-bit HMAC signature using a shared secret.

Common Claims

iat (issued at), exp (expiry), sub (subject), and iss (issuer) are standard registered claims. Custom claims can be added freely.