Token Refresh

You don't write refresh logic. The client refreshes in two situations:

1. Before expiry. If the access token is a JWT that expires within refreshSkewMs (default 30 s), the client refreshes it before sending the next request.
2. After a 401. If the server answers 401, the client refreshes and retries the request once with the new token.

Either way, requests that arrive during a refresh wait for it. Many 401s at once produce one refresh request, not one per request:

Tabs that share a session take turns refreshing through the Web Locks API, so a rotating refresh token is never spent twice.

When each one runs

The 401 retry happens once per request. A second 401 is returned as-is, so a broken server can't cause a loop. The retry gets a fresh timeout. It's skipped for skipAuth: true and refreshTokenCheck: false.

The early refresh only runs when all of these are true:

• refreshSkewMs is above 0 (0 turns it off and relies on 401s)
• the client is in header mode (in cookie mode it can't read the expiry)
• both an access token and a refresh token are stored
• the token's expiry is known and falls inside the window

An opaque (non-JWT) token has no readable expiry, so it's never refreshed early; the 401 path still covers it. If you know the expiry, pass expiresAt in the login response or to setTokens.

The refresh request

By default the client sends:

POST /auth/refresh
Content-Type: application/json

{ "refresh": "<refresh token>" }

and reads the new tokens from the response the same way it reads the login response. It carries the CSRF header like any write, and it's bounded by the client timeout.

If the response has a new refresh token, it replaces the old one (refresh-token rotation). If it has only an access token, the old refresh token is kept.

Custom token shapes

If your server uses other field names, describe them:

createClient({
  // response: { result: { jwt: "…", renew: "…", expires_in: 900 } }
  extractTokens: {
    accessKeys: ["jwt"],
    refreshKeys: ["renew"],
    expiresInKeys: ["expires_in"],   // seconds from now
    expiryKeys: ["exp_at"],          // or an absolute time, in seconds or ms
    roots: ["result"],
  },
  // request body: { "refresh_token": "…" }
  buildRefreshBody: { field: "refresh_token" },
});

The same extractTokens is used for login and for refresh. Both options also accept a function, but a function can't be sent into the Web Worker, so passing one turns worker isolation off. Prefer the object forms above.

When refresh fails

A server hiccup never logs the user out.

Manual refresh and long uploads

const ok = await api.refresh();   // true when the session is usable again

// A 10-minute upload: refresh first if the token dies within 10 minutes.
await api.post("/upload", file, { uploadSkewMs: 10 * 60_000 });

refresh() returns a boolean, not the token: the token never leaves the worker. Manual calls join any refresh already in flight, so it's safe to call from a heartbeat. In header mode with no refresh token stored it returns false without a request.

uploadSkewMs works even when refreshSkewMs is 0, because it states what this one request needs.

To skip the 401 → refresh → retry flow for one call, pass refreshTokenCheck: false. Do that for auth calls you make yourself (OTP checks, token exchanges), so a failing one can't trigger a refresh.

JWT helpers

The expiry helpers the client uses are exported:

import { getTokenExpiry, isTokenExpired } from "@mrzr/api-client";

getTokenExpiry(token);          // epoch ms, or null if it isn't a JWT with an exp claim
isTokenExpired(token);          // false when the expiry is unknown
isTokenExpired(token, 60_000);  // will it be expired a minute from now?

They only decode. They never verify the signature: that's your server's job.

Debugging

api.onAuthStateChange((s) => console.log(s.expiresAt && new Date(s.expiresAt))) shows each refresh as it happens.