useTokenLifecycle

import { useTokenLifecycle } from "@0xmonaco/react";

const {
  initializeTokens,
  clearTokens,
  refreshTokens,
  isTokenExpired
} = useTokenLifecycle(sdk, config);

Manages the lifecycle of the authenticated session: persists the session across reloads and refreshes it before it expires. The session is the wallet-authorized ed25519 keypair returned by login(); there are no separate access or refresh tokens. Most apps don’t use this hook directly; MonacoProvider wires it up and useAuth drives it. See React SDK setup.

Parameters

MonacoSDK | null

required

Monaco SDK instance from useMonacoSDK()

TokenLifecycleConfig

Session lifecycle options:

autoRefresh: boolean (default: true) - automatically extend the session before it expires
persistTokens: boolean (default: true) - persist the session in localStorage so it survives reloads
refreshBufferSeconds: number (default: 300) - how long before expiry to trigger a refresh
onRefreshError: (error: Error) => void - called when a refresh fails
onRefreshSuccess: (authState: AuthState) => void - called when a refresh succeeds

Return Values

(authState: AuthState) => void

Start managing a session. Call after a successful login(); persists the session (if enabled) and schedules auto-refresh.

() => void

Stop managing the session, cancel scheduled refreshes, and remove the persisted session. Call on logout.

() => Promise<AuthState | null>

Extend the session’s expiry now (via sdk.refreshAuth()). Returns the updated AuthState, or null if there is no active session or the refresh fails.

(authState: AuthState | null) => boolean

Whether the session is expired or within the refresh buffer of expiry.

Example

import { useMonacoSDK, useTokenLifecycle } from "@0xmonaco/react";

function SessionManager() {
  const { sdk } = useMonacoSDK();

  const {
    initializeTokens,
    clearTokens,
    refreshTokens,
    isTokenExpired
  } = useTokenLifecycle(sdk, {
    autoRefresh: true,
    persistTokens: true,
    refreshBufferSeconds: 300, // refresh 5 minutes before expiry
    onRefreshError: (error) => {
      console.error('Session refresh failed:', error);
      // Handle logout or re-authentication
    },
    onRefreshSuccess: (authState) => {
      console.log('Session extended to', authState.expiresAt);
    },
  });

  // After a successful login
  const handleLoginSuccess = (authState) => {
    initializeTokens(authState);
  };

  // On logout
  const handleLogout = () => {
    clearTokens();
  };

  // Manual refresh if needed
  const handleManualRefresh = async () => {
    const newAuthState = await refreshTokens();
    if (!newAuthState) {
      console.log('Refresh failed, need to re-authenticate');
    }
  };

  return (
    <div>
      <button onClick={handleManualRefresh}>Refresh Session</button>
      <button onClick={handleLogout}>Logout</button>
    </div>
  );
}

How It Works

Auto Refresh: when enabled, schedules a session refresh refreshBufferSeconds before expiry.
Persistence: saves the session to localStorage so it can be restored after a reload.
Deduplication: collapses concurrent refresh calls into a single request.
Cleanup: clears scheduled timers on unmount.

When persistTokens is enabled, the persisted session includes the ed25519 session private key. This credential signs every request. localStorage is readable by any script on your origin, so harden against XSS (e.g. a strict Content Security Policy) and always clearTokens() on logout. Disable persistTokens to keep the session in memory only.

This is an advanced hook. For most apps, MonacoProvider + useAuth manage the session automatically.

Learn

Build

Libraries

APIs

Resources

Parameters

Return Values

Example

How It Works

​Parameters

​Return Values

​Example

​How It Works

Parameters

Return Values

Example

How It Works