AuthClientConfig

Defined in: auth-client/src/core/types.ts:86

Configuration for createAuthClient — every field is optional except apiBaseUrl. Defaults give a sensible browser experience.

Properties

apiBaseUrl

apiBaseUrl: string

Defined in: auth-client/src/core/types.ts:89

Base URL of the auth-server, e.g. “https://auth.ryanweiss.net/api/v1”. No trailing slash. The SDK appends “/auth/login” etc.

appCode?

optional appCode?: string

Defined in: auth-client/src/core/types.ts:93

App scoping — required by the auth-server unless AUTH_ALLOW_BASE_USER_LOGIN is set. Persists across the session.

attachAuthHeader?

optional attachAuthHeader?: boolean

Defined in: auth-client/src/core/types.ts:108

When true (default), the SDK attaches an Authorization header to fetch calls made via the package’s HTTP helper. Disable if your app uses cookie-based auth (set HttpOnly cookie via /auth/login).

autoRefresh?

optional autoRefresh?: boolean

Defined in: auth-client/src/core/types.ts:146

When true, the SDK schedules a background refresh ~refreshLeewaySeconds before the cached access token expires. An actively-used app re-mints transparently — the snapshot never flips to ‘anonymous’. Default true.

Disable for: SSR contexts (no need to schedule on the server), test harnesses that drive the clock manually, or any environment where a long-running timer would leak.

autoRetryOn401?

optional autoRetryOn401?: boolean

Defined in: auth-client/src/core/types.ts:136

When true, the SDK auto-refreshes + retries on 401 for calls made through authenticatedRequest(). On refresh failure, emits session_expired and clears local state. Default true.

bootstrap?

optional bootstrap?: "offline" | "auto" | "lazy"

Defined in: auth-client/src/core/types.ts:131

Strategy for the initial auth check at construction time.

‘auto’ (default): on construct, the client reads cached tokens, refreshes if near-expiry, and confirms the session via /auth/me. ready() resolves once that handshake completes (or fails). UIs typically gate their first render on ready().
‘lazy’: skip the proactive check. Trust the cached state until the first request fails. Cheaper boot, at the cost of possibly rendering an authenticated UI for a tick before the server tells us otherwise.
‘offline’: disable all auth. isAuthenticated() returns false, getCurrentUser() returns null. Flow methods that would make a network call throw OfflineModeError. Useful for embedding the SDK in static demos / styleguides / Storybook.

enableCrossTabSync?

optional enableCrossTabSync?: boolean

Defined in: auth-client/src/core/types.ts:114

Per-tab default: false. When true, the SDK uses BroadcastChannel to publish auth events (“authenticated”, “loggedOut”) so multiple tabs stay in sync. Falls back to a no-op when BroadcastChannel is unavailable (older browsers / SSR).

idleTimeoutMs?

optional idleTimeoutMs?: number

Defined in: auth-client/src/core/types.ts:161

Optional client-side inactivity policy. When set, the SDK starts an IdleTracker that watches DOM activity (pointer/keyboard/scroll/ visibility) and clears local auth state after idleTimeoutMs of inactivity, signing the user out locally. The server-side refresh token remains valid until its natural exp; the user re-logs in via the normal login flow.

Browser-only. Has no effect in non-DOM environments.

Recommended values: 15-30 minutes for sensitive admin tooling, 60+ minutes for general consumer apps. Leave undefined (the default) for “stay signed in as long as the refresh token is valid” semantics — the common consumer-app pattern.

ports?

optional ports?: Partial<AuthClientPorts>

Defined in: auth-client/src/core/types.ts:166

Override the default ports (storage, transport, etc.) — see AuthClientPorts. Useful for SSR (memory storage, fetch polyfill) or tests (deterministic clock, instrumented transport).

refreshLeewaySeconds?

optional refreshLeewaySeconds?: number

Defined in: auth-client/src/core/types.ts:103

Refresh leeway in seconds — when the access token is within this window of expiry, the SDK preemptively refreshes on the next fetch interception. Default: 60.

storageNamespace?

optional storageNamespace?: string

Defined in: auth-client/src/core/types.ts:98

Storage namespace prefix for token-store keys. Lets two installs of the SDK on the same origin coexist without colliding (e.g., marketplace + admin in the same tab). Default: “rw3iss_auth”.