layout
page
server component
route handler
server action
BFF endpoint
middleware/proxy

refresh token rotation races
stale cookie writes
hydration mismatch
partial render failures
redirect loops
cache contamination

Refresh is not a helper function.
Refresh is a session state transition.

At the request boundary, load session, decide whether refresh is needed, refresh once, then render everything with a stable session snapshot.

single refresh decision
fewer partial render failures
stable session projection
simpler cache keys
less hydration mismatch

adds request-boundary work even if page data is public-ish
requires a central request/auth boundary
harder if framework does not expose one cleanly

Each server-side API fetch handles 401/expired token and triggers refresh if needed.

localized handling
works when token expiry is discovered by downstream API
can avoid unnecessary refresh

race-prone
waterfall-prone
harder cookie mutation
more repeated logic
may render inconsistent session state

Refresh proactively once near the request boundary when expiry is near.
Still handle reactive 401 from downstream APIs safely.

type SessionSnapshot = {
  sessionId: string;
  userId: string;
  tenantId: string | null;
  expiresAt: string;
  refreshedAt: string | null;
  authTime: string;
  assuranceLevel: "aal1" | "aal2" | "aal3";
  permissionEpoch: number;
};

refresh token
access token
provider token
session secret
raw JWT unless needed server-side only
policy trace
sensitive claims not required by UI

type ClientSessionProjection = {
  kind: "authenticated";
  user: {
    id: string;
    displayName: string;
  };
  tenant: {
    id: string;
    slug: string;
    displayName: string;
  } | null;
  expiresAt: string;
  assuranceLevel: "aal1" | "aal2" | "aal3";
  permissionEpoch: number;
};

Not every server-side place that can read cookies can write cookies.

server rendered with new token internally
browser still holds old cookie
next request repeats refresh or fails

Route Handler / BFF endpoint
Server Action when invoked as mutation
explicit session refresh endpoint
request bootstrap endpoint

browser holds HttpOnly app session cookie
server holds refresh token / provider token in token vault
server refreshes provider tokens when needed
browser never sees provider refresh token

Only the server sees provider tokens.

const REFRESH_WINDOW_SECONDS = 120;

function shouldRefresh(expiresAtMs: number, nowMs: number) {
  return expiresAtMs - nowMs <= REFRESH_WINDOW_SECONDS * 1000;
}

access token lifetime: short
refresh threshold: small buffer for network/render time
clock skew leeway: explicit and bounded
refresh lock TTL: short
server session idle/absolute expiry: independent

type TokenTiming = {
  accessTokenExpiresAt: number;
  refreshTokenExpiresAt: number;
  appSessionExpiresAt: number;
  idleExpiresAt: number;
  absoluteExpiresAt: number;
};

For one session/token family, only one refresh operation runs at a time.
Other callers wait for the result or reuse the updated token state.

const inFlightRefresh = new Map<string, Promise<RefreshResult>>();

export async function refreshSingleFlight(sessionId: string) {
  const existing = inFlightRefresh.get(sessionId);
  if (existing) return existing;

  const promise = actuallyRefresh(sessionId).finally(() => {
    inFlightRefresh.delete(sessionId);
  });

  inFlightRefresh.set(sessionId, promise);
  return promise;
}

multiple server instances
multiple regions
serverless concurrent invocations
edge + origin split

session store row lock
distributed lock
compare-and-swap token version
refresh token family version

1. read refresh token A
2. call IdP with A
3. receive refresh token B
4. write B

type TokenRecord = {
  sessionId: string;
  refreshTokenHash: string;
  encryptedRefreshToken: string;
  accessTokenExpiresAt: number;
  version: number;
};

1. load token record with version N
2. acquire lock or compare-and-swap intent
3. call IdP with current refresh token
4. receive new token set
5. update only if version still N
6. write version N+1
7. release lock

async function refreshTokenFamily(sessionId: string) {
  return await tokenStore.withSessionLock(sessionId, async () => {
    const current = await tokenStore.get(sessionId);

    if (!shouldRefresh(current.accessTokenExpiresAt, Date.now())) {
      return current;
    }

    const next = await idp.refresh(decrypt(current.encryptedRefreshToken));

    await tokenStore.updateIfVersion(sessionId, current.version, {
      encryptedAccessToken: encrypt(next.accessToken),
      encryptedRefreshToken: encrypt(next.refreshToken ?? current.refreshToken),
      accessTokenExpiresAt: next.accessTokenExpiresAt,
      version: current.version + 1,
    });

    return await tokenStore.get(sessionId);
  });
}

access token revoked
clock skew
key rotation
scope/audience mismatch
token family revoked
IdP incident
API auth cache stale

Only retry once.
Only retry idempotent requests automatically.
For mutations, use idempotency keys or do not auto-replay.
If refresh fails, clear session and return typed auth error.

type FetchAuthMode = "idempotent" | "mutation";

async function fetchWithServerAuth(input: RequestInfo, init: RequestInit & { authMode: FetchAuthMode }) {
  const token = await getValidAccessTokenForRequest();

  let res = await fetch(input, {
    ...init,
    headers: {
      ...init.headers,
      Authorization: `Bearer ${token.value}`,
    },
  });

  if (res.status !== 401) return res;

  if (init.authMode === "mutation") {
    // Do not blindly replay non-idempotent mutations.
    return res;
  }

  await refreshSingleFlight(token.sessionId);
  const next = await getValidAccessTokenForRequest();

  res = await fetch(input, {
    ...init,
    headers: {
      ...init.headers,
      Authorization: `Bearer ${next.value}`,
    },
  });

  return res;
}

idempotency key
server-side transaction identity
explicit retry contract

await fetch(url, {
  cache: "no-store",
});

const me = await fetch("https://api.example.com/me").then(r => r.json());

export async function authFetch(input: string, init: RequestInit = {}) {
  const session = await requireServerSession();
  const token = await getValidAccessTokenForRequest(session);

  return fetch(input, {
    ...init,
    cache: "no-store",
    headers: {
      ...init.headers,
      Authorization: `Bearer ${token.value}`,
      "X-Request-Session": session.sessionId,
    },
  });
}

let currentSession: SessionSnapshot | null = null;

server rendered authenticated page
client bootstraps as anonymous
server used refreshed session but browser cookie was not updated
client cache still has old permission epoch
user logs out in another tab between SSR and hydration
tenant switched in another tab

embed safe session projection from server
include auth epoch / session version
clear client caches when epoch changes
never expose tokens in projection
prefer no-store for authenticated SSR
handle client-side session reconciliation after hydration

<AuthProvider
  initialSession={{
    kind: "authenticated",
    user: { id: user.id, displayName: user.displayName },
    tenant: tenantProjection,
    expiresAt: session.expiresAt,
    permissionEpoch: session.permissionEpoch,
    sessionVersion: session.version,
  }}
>
  {children}
</AuthProvider>

initial session version
current /session endpoint version
cross-tab auth epoch

Server Component calls session bootstrap/read helper.
If refresh is required, delegate to Route Handler/BFF/session service or ensure refresh occurred before render.
Mutations perform their own fresh auth check and refresh if needed.

read session cookie
load session record
refresh if allowed and needed
return stable snapshot
memoize within request
never expose raw tokens to Client Components

type RequireSessionOptions = {
  allowRefresh: boolean;
  requiredAssurance?: "aal1" | "aal2" | "aal3";
};

export async function requireSessionForRequest(options: RequireSessionOptions) {
  const cookie = await readSessionCookie();
  if (!cookie) throw new AuthError("missing_session");

  const session = await sessionStore.load(cookie.sessionId);
  if (!session) throw new AuthError("invalid_session");

  if (isExpired(session)) throw new AuthError("expired_session");

  if (options.allowRefresh && shouldRenewAppSession(session)) {
    return await renewAppSessionSingleFlight(session.id);
  }

  if (options.requiredAssurance && !meetsAssurance(session, options.requiredAssurance)) {
    throw new AuthError("step_up_required");
  }

  return toSessionSnapshot(session);
}

export async function DashboardPage() {
  const session = await requireSessionForRequest({ allowRefresh: true });
  const data = await getDashboardData(session);
  return <Dashboard initialData={data} />;
}

Your application extends or rotates its own session cookie/session record.

idle timeout extended from 14:00 to 14:30
session cookie renewed
session version incremented

Your server refreshes OAuth access token using provider refresh token.

access token for downstream API expires in 60 seconds
server uses refresh token grant
new access token stored in token vault

type SessionRecord = {
  id: string;
  idleExpiresAt: number;
  absoluteExpiresAt: number;
  cookieExpiresAt: number;
  permissionEpoch: number;
};

type ProviderTokenRecord = {
  sessionId: string;
  provider: "auth0" | "cognito" | "workos" | "custom";
  accessTokenExpiresAt: number;
  refreshTokenExpiresAt: number | null;
  tokenFamilyVersion: number;
};

idle timeout: extended by activity
absolute timeout: hard maximum lifetime

function canRenewSession(session: SessionRecord, now: number) {
  if (now >= session.absoluteExpiresAt) return false;
  if (now >= session.idleExpiresAt) return false;
  return true;
}

renew only when idle expiry is near
renew only for meaningful app activity
avoid renewing on asset requests/prefetches/health checks
avoid renewing on aggressive polling unless intentional

hovering a link renews session
background prefetch rotates token
prefetch races with active navigation
prefetch keeps session alive unintentionally

prefetch may read cache-safe public data
prefetch should not renew idle session by default
prefetch should not perform provider token refresh unless required and explicit
prefetch must not perform mutations

open multiple tabs
hard refresh page
navigation + data request
parallel route segments
browser retry
CDN/origin retry

session lock or token version CAS
refresh token family version
idempotent session renewal
clear failure semantics
bounded retry
metrics

if refresh token reuse is detected -> revoke session family -> force logout all tabs
if refresh lock times out -> return 503/degraded or retry once
if provider unavailable -> keep current valid token if still valid, otherwise degrade/reauth

Session refreshed successfully, therefore page may render.

Session refreshed successfully, therefore identity continuity is valid.
Now check authorization for the route/resource/action.

user logged in 8 hours ago
session is still valid
access token refreshed 2 minutes ago
user wants to approve high-risk payment

auth_time
acr/amr
assurance level
risk signal
sensitive action policy

{
  "type": "auth.step_up_required",
  "requiredAssurance": "aal2",
  "returnTo": "/app/payments/123/approve"
}

Tab A: user clicks logout
Tab B: hidden tab refreshes /app/dashboard
Server: refreshes session for Tab B
Tab A: logout clears cookie
Tab B: receives renewed cookie or rendered app

session store has revokedAt/sessionVersion
logout revokes session server-side first
refresh checks revokedAt inside lock
Set-Cookie from stale refresh is rejected by version check
client auth epoch propagates logout across tabs

A revoked session must not be renewed.

parallel route handlers write different Set-Cookie values
older response arrives after newer response
browser stores stale cookie

centralize cookie write per request
include session version in cookie/session record
reject stale session versions server-side
avoid multiple refresh-capable endpoints firing concurrently
make refresh endpoint single-flight

browser cookie version is not authority
server session store is authority

SSR response varies by Cookie but cache does not vary correctly

Cache-Control: no-store
Vary: Cookie, Authorization
private caching only when explicitly understood

public shell/static marketing content can cache
private user/session data fetched from no-store endpoint

session.refresh.attempt.count
session.refresh.success.count
session.refresh.failure.count
session.refresh.singleflight.wait.count
session.refresh.lock.timeout.count
session.refresh.rotation_reuse_detected.count
session.refresh.provider_latency.p95
session.refresh.per_request.count
session.render.auth_snapshot_mismatch.count

request_id
session_id_hash
user_id_hash
tenant_id_hash
token_family_version
refresh_reason: proactive | reactive_401 | idle_renewal
result: success | invalid_grant | provider_unavailable | lock_timeout

access token
refresh token
raw cookie value
full JWT
authorization header

refreshing token inside every server component
using module-level current user/session
retrying every 401 mutation automatically
refreshing session on every request, including assets/prefetch
storing provider refresh token in browser
assuming refreshed token means permission allowed
caching authenticated SSR without Vary/no-store discipline
writing cookies from multiple uncoordinated places
using edge middleware as refresh token vault
ignoring logout/refresh race

Is there one request-scoped session snapshot?
Is refresh single-flight per session/token family?
Is provider token refresh separate from app session renewal?
Are refresh token rotations atomic?
Can revoked sessions never be renewed?
Are non-idempotent mutations protected from blind retry?
Can cookie writes happen only in valid server contexts?
Are authenticated SSR responses no-store unless explicitly safe?
Does hydration compare session/auth epoch?
Does logout win against refresh?
Are provider outage paths fail-closed or intentionally degraded?
Are refresh metrics and lock timeouts observable?

One request should render from one stable session snapshot.
One session should have at most one refresh transition at a time.
One successful refresh should not bypass one authorization check.