Skip to main content

Session Management

Use useSession when an account screen needs the active profile or the user's server-side sessions. It reads the active OvokClient; your app still owns route protection and the destination after sign-in or sign-out.

Read session state​

Render the hook below OvokProvider. This example checks loading and errors before rendering a signed-out state.

import { useSession } from "@ovok/native";
import { Button, Text } from "react-native-paper";

export function SecurityStatus() {
  const {
    status,
    reason,
    profile,
    sessions,
    loading,
    switching,
    error,
    refresh,
  } = useSession({ sessions: true, refreshOnForeground: true });

  if (loading) return <Text>Loading account…</Text>;

  if (error) {
    return (
      <>
        <Text>We couldn't refresh your account state.</Text>
        <Button onPress={() => void refresh()}>Try again</Button>
      </>
    );
  }

  if (status === "signed-out") {
    return (
      <Text>
        {reason === "session-ended"
          ? "Your session ended. Sign in again."
          : "Sign in to view account security."}
      </Text>
    );
  }

  return (
    <>
      <Text>Patient: {profile?.id}</Text>
      <Text>Active sessions: {sessions.length}</Text>
      {switching && <Text>Updating account…</Text>}
    </>
  );
}

The hook returns status (loading, authenticated, offline, or signed-out), isAuthenticated, saved accounts, profile, normalized sessions, loading, switching, reason, error, refresh, refreshSessions, switchAccount, removeAccount, logout, and revokeSessions. offline means the saved login is still present but profile refresh failed; it remains authenticated. The hook retries when connectivity returns. reason is "session-ended" when the client clears an active login unexpectedly; it is absent after a user-requested logout.

Refresh and revoke sessions​

sessions and refreshOnForeground both default to true. Set sessions: false when a screen only needs profile state. Set refreshOnForeground: false if the host already refreshes on app resume. The hook also refreshes when a mounted auth component publishes a session change; call refresh() after a custom auth flow that does not publish that event. Pass sessions: false when a screen only needs profile state; pass refreshOnForeground: false when the host owns app-resume refreshes.

switchAccount() and removeAccount() preserve the current status and profile while they run. Use switching to disable account controls or show local progress; do not replace the screen or navigator based on it. Removing an inactive account does not change the active session.

Account-switch recovery, offline-switch behavior, and the session-ended reason require @ovok/core 0.4.27 or later, which provides the account-management and session methods used by this hook.

Use revokeSessions("other") to sign out other sessions. The server owns the session inventory and revocation policy. The returned session fields are id, authMethod, remoteAddress, and lastUpdated when the backend provides them.

The current hook maps a refresh failure to status: "signed-out" and exposes the failure as error. Check error before treating signed-out as a confirmed logout. Its logout() method clears local hook state in a finally block, even when the server request rejects; catch the returned promise if the result affects navigation.

Use the provided session list​

<SessionList onError={handleError} /> renders the loading and empty states, lists available sessions, and offers Sign out of other devices when more than one session is present. It creates its own useSession hook; use the list on its own or build a custom list from one hook instance rather than mounting both and fetching sessions twice.

The server-side session methods require a compatible @ovok/core version with logout, getSessions, and revokeSessions.