Skip to Content
🌐 Frontend SDKHooksSession & Auth

Session & Auth

Hooks for session state, authentication, address access, logout, key recovery, and linked profiles.

EmbarkAI provides several hooks for working with session data. For most applications, useAccountSession is the recommended starting point.

Import

import {
  useAccountSession,
  useSession,
  useLoadingStatus,
  useAddress,
  useLogout,
  useHydrated,
} from '@embarkai/ui-kit'

useAccountSession

Returns the current session object when a user is authenticated, or null when disconnected. This is the recommended hook for checking authentication state.

import { useAccountSession } from '@embarkai/ui-kit'
 
function Dashboard() {
  const session = useAccountSession()
 
  if (!session) {
    return <p>Please connect your wallet.</p>
  }
 
  return <p>Welcome back! Session active.</p>
}

useSession

A lower-level hook that gives direct access to the session store via a selector function. Use this when you need fine-grained control over which store values trigger re-renders.

import { useSession } from '@embarkai/ui-kit'
 
function AddressDisplay() {
  const address = useSession((state) => state.address)
  return <span>{address ?? 'Not connected'}</span>
}

useAddress

Returns the connected smart wallet address directly:

import { useAddress } from '@embarkai/ui-kit'
 
function WalletAddress() {
  const address = useAddress()
  return <code>{address}</code>
}

useLoadingStatus

Returns the session loading state, useful for displaying spinners or skeleton screens during authentication.

import { useLoadingStatus } from '@embarkai/ui-kit'
 
function AppLoader() {
  const { isSessionLoading, sessionStatus } = useLoadingStatus()
 
  if (isSessionLoading) {
    return <div className="spinner">Loading ({sessionStatus})...</div>
  }
 
  return <main>App ready</main>
}
PropertyTypeDescription
isSessionLoadingbooleantrue while the session is being established or restored.
sessionStatusstringCurrent status label (e.g., 'hydrating', 'connecting', 'ready').

useLogout

Returns a logout function that ends the current session and clears stored credentials.

import { useLogout } from '@embarkai/ui-kit'
 
function LogoutButton() {
  const { logout } = useLogout()
 
  return <button onClick={logout}>Disconnect</button>
}

useHydrated

Returns true once the SDK has finished restoring a previous session from localStorage. Before hydration completes, session hooks may return null even if the user was previously connected.

import { useHydrated, useAccountSession } from '@embarkai/ui-kit'
 
function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const hydrated = useHydrated()
  const session = useAccountSession()
 
  if (!hydrated) return <p>Restoring session...</p>
  if (!session) return <p>Please connect to continue.</p>
 
  return <>{children}</>
}

useRecoveryUserId

Returns the user ID used for MPC key recovery. This is set during initial wallet creation and is required when restoring keys on a new device.

import { useRecoveryUserId } from '@embarkai/ui-kit'
 
function RecoveryInfo() {
  const recoveryUserId = useRecoveryUserId()
 
  if (!recoveryUserId) return null
 
  return <p>Recovery ID: {recoveryUserId}</p>
}

useHasServerVault

Returns whether the current user has a server-side key vault (ShareVault backup). When true, the user can recover their wallet without the original device.

import { useHasServerVault } from '@embarkai/ui-kit'
 
function VaultStatus() {
  const hasVault = useHasServerVault()
 
  return (
    <p>
      Key backup: {hasVault ? 'Enabled ✓' : 'Not configured'}
    </p>
  )
}

useLinkedProfiles

Returns the list of social and email profiles linked to the current account (e.g., Google, GitHub, email).

import { useLinkedProfiles } from '@embarkai/ui-kit'
 
function LinkedAccounts() {
  const profiles = useLinkedProfiles()
 
  if (!profiles?.length) return <p>No linked accounts.</p>
 
  return (
    <ul>
      {profiles.map((profile) => (
        <li key={profile.id}>
          {profile.provider}: {profile.identifier}
        </li>
      ))}
    </ul>
  )
}

Return Value

Each profile object contains:

PropertyTypeDescription
idstringUnique profile identifier.
providerstringProvider name (e.g., 'google', 'github', 'email').
identifierstringEmail address or username.

Session Lifecycle

The session moves through these stages after the Provider mounts:

  1. Hydrating — SDK checks localStorage for a stored session.
  2. Connecting — User initiates authentication (passkey, email, social, or external wallet).
  3. Establishing — MPC key generation or key recovery is in progress.
  4. Ready — Session is active, all hooks return live data.
  5. Disconnected — User logs out or the session expires.

Use useLoadingStatus to track these transitions and useHydrated to know when step 1 is complete.

Full Example

import {
  useAccountSession,
  useAddress,
  useLoadingStatus,
  useLogout,
  useHydrated,
} from '@embarkai/ui-kit'
 
function UserProfile() {
  const hydrated = useHydrated()
  const session = useAccountSession()
  const address = useAddress()
  const { isSessionLoading } = useLoadingStatus()
  const { logout } = useLogout()
 
  if (!hydrated || isSessionLoading) return <p>Loading...</p>
  if (!session) return <p>Not connected</p>
 
  return (
    <div>
      <p>Wallet: {address}</p>
      <button onClick={logout}>Sign Out</button>
    </div>
  )
}

Next Steps

Last updated on
OverviewBalance & Assets