Understanding JWT Claims and Token Renewal Strategies

The payload of a JWT token is a JSON string that carries a set of statements called claims. The JWT specification defines several standard claims, including iss (issuer), sub (subject), aud (audience), exp (expiration time), nbf (not before), iat (issued at), and jti (JWT ID).

In addition to these, developers can define custom claims. The example below (using the com.auth0 library) creates a token with an expiration time and a custom claim named username :

String token = JWT.create()
    .withIssuer(ISSUER)
    .withIssuedAt(new Date(currentTime)) // 签发时间
    .withExpiresAt(new Date(currentTime + EXPIRES_IN * 1000 * 60)) // 过期时间戳
    .withClaim("username", username) // 自定义参数
    .sign(Algorithm.HMAC256(user.getPassword()));

The code uses withIssuer() to set the issuer, withIssuedAt() for the issuance time, withExpiresAt() for the expiration timestamp, and withClaim() for custom data.

When a token expires, the client must obtain a new one, which can lead to a poor user experience if it happens frequently. To improve this, many applications implement token renewal mechanisms.

Single‑token renewal scheme :

Set token expiration (e.g., 15 minutes).

The frontend checks token validity on each request; if expired, it requests a refreshed token from the backend.

The backend returns a new token, and the frontend retries the original request.

Additional rules can enforce re‑login after a certain period (e.g., 72 hours) or limit the number of refreshes.

Double‑token scheme :

After successful login, the backend issues an access_token and a refresh_token .

The client uses the access_token for API calls; when it expires, the client sends the refresh_token to obtain a new access_token .

The backend validates the refresh_token ; if it is still valid, a new access_token is returned, otherwise the client must re‑authenticate.

Logout or password change invalidates both tokens.

WeChat web authorization also follows a double‑token model based on OAuth 2.0: a short‑lived access_token (≈2 hours) and a long‑lived refresh_token (≈30 days). The authorization code obtained from the user is valid for 10 minutes and can be exchanged for these tokens only once.

For server‑side token management, Redis can be used to store tokens with an expiration time; the absence of a token key in Redis indicates that the token has expired.