Implementing Secure Double‑Token Authentication in WeChat Mini‑Programs

Double Token Concept

AccessToken

Purpose: used to access protected APIs.

Characteristics: short lifespan (e.g., 15 minutes to 1 hour) to reduce theft risk.

Expiration handling: a new AccessToken must be obtained via RefreshToken.

RefreshToken

Purpose: used to refresh the AccessToken.

Characteristics: long lifespan (e.g., 7 days or more); typically invalidated only on high‑risk actions or user logout.

Expiration handling: requires the user to log in again.

Double Token Design Flow

Login Process Highlights:

User Login

The user calls wx.login() to obtain a temporary login credential (code).

The front‑end sends the code to the back‑end, which exchanges it for the user's OpenID and SessionKey via WeChat's login API.

Generate Tokens

The back‑end creates an AccessToken and a RefreshToken based on the user information.

Both tokens are standard JWTs; the AccessToken gets a short expiration, the RefreshToken a longer one.

Return Tokens

The back‑end returns the two tokens to the Mini‑Program front‑end for subsequent API calls.

Refresh Token

When the AccessToken expires, the front‑end calls a refresh endpoint with the RefreshToken to obtain a new AccessToken.

If the RefreshToken is also invalid, the user must log in again.

Mini‑Program API Request Design Points

Validate User Login State

If no AccessToken is found and the request is not an auth‑related API (e.g., login), perform a silent login.

If an AccessToken exists, proceed with wx.request.

Use AccessToken for API Calls

Include the AccessToken in the HTTP header when calling back‑end APIs.

The back‑end validates the token via a filter.

If valid, the requested resource is returned.

Determine Whether the API Is an Auth Endpoint

The front‑end checks if the API name is login, refresh, or similar.

If it is, propagate the backend error directly.

Otherwise, continue handling 401/403 errors.

AccessToken Expired (401)

The back‑end returns 401 when the AccessToken is missing, expired, or invalid.

The Mini‑Program receives 401, then calls the refresh endpoint with the RefreshToken.

If the RefreshToken is valid, a new AccessToken is obtained and the original request is retried.

RefreshToken Expired

If the refresh endpoint finds the RefreshToken empty, expired, or illegal, it returns 401.

The front‑end wrapper treats this as an exception, triggers a full login flow, and retries the original API upon success.

On repeated failure, an error message is shown and the request is aborted.

AccessToken Valid but Insufficient Permissions (403)

The back‑end accepts the token but denies access due to insufficient user rights, returning 403.

The Mini‑Program calls the logout endpoint and redirects the user to the login page or home screen.

Conclusion

Using a double‑token scheme greatly improves the user experience in WeChat Mini‑Programs by reducing the frequency of login prompts. During development, thoroughly test scenarios where AccessToken and RefreshToken expire to avoid infinite retry loops.