Client Integration

Last updated


This page explains how browser and non-browser clients send tokens and pick up refreshed values.

Browsers (Cookies)


Tokens live in httpOnly cookies that frontend code cannot read and does not need to handle; requests only have to carry the cookies:
  1. async function loadProfile() {
  2. const res = await fetch("https://api.example.com/me", {
  3. // Required to send cookies cross-origin
  4. credentials: "include",
  5. });
  6. if (res.status === 401) {
  7. // Not logged in or already logged out
  8. window.location.href = "/login";
  9. return;
  10. }
  11. if (!res.ok) throw new Error(`HTTP ${res.status}`);
  12. return res.json();
  13. }

The server refreshes through Set-Cookie, so the frontend needs no extra handling.

Non-Browser Clients (Headers)


Mobile apps, CLIs, or server-to-server calls without cookies send headers and update local values from the response headers:
  1. type Session = { accessToken: string; refreshId: string; deviceId: string };
  2. async function callApi(session: Session, url: string) {
  3. const res = await fetch(url, {
  4. headers: {
  5. Authorization: `Bearer ${session.accessToken}`,
  6. "X-Refresh-ID": session.refreshId,
  7. // Part of the fingerprint; must match the value used at login
  8. "X-Device-ID": session.deviceId,
  9. },
  10. });
  11. const newToken = res.headers.get("X-New-Access-Token");
  12. const newRefreshId = res.headers.get("X-New-Refresh-ID");
  13. if (newToken) session.accessToken = newToken;
  14. if (newRefreshId) session.refreshId = newRefreshId;
  15. if (!res.ok) throw new Error(`HTTP ${res.status}`);
  16. return res.json();
  17. }

The { token, refresh_id } returned by CreateJWT() at login are the initial accessToken and refreshId.

Notes


ItemDetail
Device IDGenerate it on the client and persist it (for example, a UUID created at install); send the same value on every request
Concurrent requestsAfter rotation the old Refresh ID survives only 5 seconds; after long idle periods, refresh with a single request before fanning out
Response headersCross-origin servers must list X-New-Access-Token and X-New-Refresh-ID in Access-Control-Expose-Headers

Related: Token Transport, Device Fingerprint
中文