Mastering JWT Claims and Token Renewal: From Single to Double Token Schemes

Standard JWT Claims

The payload of a JWT is a JSON string that carries a set of statements called claims. The JWT specification defines several standard claims: iss (Issuer): the entity that issued the JWT. sub (Subject): the principal that is the subject of the JWT. aud (Audience): the intended recipient of the JWT. exp (Expiration time): the time after which the JWT must not be accepted. nbf (Not Before): the time before which the JWT must not be accepted. iat (Issued at): the time at which the JWT was issued. jti (JWT ID): a unique identifier for the JWT.

In addition to these, custom claims can be added. The example below uses the com.auth0 library to create a token with an expiration time and a custom "username" claim.

String token = JWT.create()
    .withIssuer(ISSUER)
    .withIssuedAt(new Date(currentTime)) // signing time
    .withExpiresAt(new Date(currentTime + EXPIRES_IN * 1000 * 60)) // expiration timestamp
    .withClaim("username", username) // custom parameter
    .sign(Algorithm.HMAC256(user.getPassword()));

The following methods are used: withIssuer(): set the issuer. withIssuedAt(): set the issuance time. withExpiresAt(): set the expiration timestamp (duration defined by EXPIRES_IN in seconds). withClaim(): add a custom claim.

Token Expiration and Renewal

When a JWT expires, the client must obtain a new token, typically by logging in again. Frequent forced logins degrade user experience, so many applications implement automatic token renewal.

Single‑Token Renewal Scheme

Set the token expiration to 15 minutes.

The frontend sends a request; the backend checks if the token is expired.

If expired, the frontend requests a token refresh; the backend returns a new token.

The frontend retries the original request with the new token.

Optionally, enforce a hard re‑login after a fixed period (e.g., 72 hours) by recording the last login time and rejecting refresh requests that exceed the limit.

Limit the number of refreshes (e.g., max 50) to force re‑authorization when the limit is reached.

Double‑Token Scheme

After a successful login, the backend returns both an access_token (short‑lived) and a refresh_token (long‑lived) which the client stores.

The client uses the access_token to call protected APIs. If the access token is expired, the client sends the refresh_token to a token‑refresh endpoint.

The backend validates the refresh_token. If it is still valid, a new access_token is issued and returned.

The client retries the original API call with the new access token.

When the user logs out or changes the password, both tokens are invalidated, forcing a fresh login.

Redis‑Based Token Storage

Tokens can also be stored in Redis with an expiration time. If a token key is missing in Redis, it is considered expired.

WeChat Web Authorization (OAuth 2.0) – A Double‑Token Example

The user authorizes the third‑party app on a WeChat page and receives a code (valid for 10 minutes, one‑time use).

The app exchanges the code for an access_token and a refresh_token. access_token is used to call protected APIs and expires after 2 hours. refresh_token lasts up to 30 days; when it expires, the user must re‑authorize.

These patterns illustrate how to manage JWT lifecycles securely and improve user experience by minimizing unnecessary logins.