Skip to main content
The useSession hook provides access to the current user session state and methods for managing user authentication and context switching.

​
Import

import { useSession } from '@snipextt/wacht';

​
Usage

import { useSession } from '@snipextt/wacht';

function MyComponent() {
  const { 
    session, 
    loading, 
    switchOrganization, 
    switchWorkspace, 
    signOut,
    getToken,
    addNewAccount 
  } = useSession();

  if (loading) {
    return <div>Loading session...</div>;
  }

  if (!session) {
    return <div>Not authenticated</div>;
  }

  return (
    <div>
      <h1>Welcome, {session.user.first_name}!</h1>
      <button onClick={() => signOut()}>
        Sign Out
      </button>
    </div>
  );
}

​
Properties

​
session
Session | null
The current user session object containing user data, active sign-ins, and organization/workspace memberships. null if not authenticated.
​
loading
boolean
Whether the session is currently being loaded. true during initial authentication check.
​
error
Error | null
Any error that occurred while loading the session. null if no errors.

​
Methods

​
switchSignIn()

Switches between multiple user sign-ins within the same session.
​
signInId
string
required
The ID of the sign-in to switch to
const { switchSignIn } = useSession();

// Switch to a different sign-in
await switchSignIn('signin_123');

​
switchOrganization()

Switches the active organization context for the current user.
​
organizationId
string
The ID of the organization to switch to. If not provided, switches to personal workspace.
const { switchOrganization } = useSession();

// Switch to specific organization
await switchOrganization('org_123');

// Switch to personal workspace
await switchOrganization();

​
switchWorkspace()

Switches the active workspace context within the current organization.
​
workspaceId
string
required
The ID of the workspace to switch to
const { switchWorkspace } = useSession();

// Switch to specific workspace
await switchWorkspace('workspace_123');

​
signOut()

Signs out the current user or a specific sign-in.
​
signInId
string
The ID of the specific sign-in to sign out. If not provided, signs out all sign-ins.
const { signOut } = useSession();

// Sign out all sessions
await signOut();

// Sign out specific session
await signOut('signin_123');

​
getToken()

Retrieves a session token for API authentication.
​
template
string
The token template to use. Defaults to “default”.
const { getToken } = useSession();

// Get default token
const token = await getToken();

// Get custom template token
const apiToken = await getToken('api');

​
addNewAccount()

Redirects the user to add a new account while maintaining the current session. 
const { addNewAccount } = useSession();

// Redirect to add new account
addNewAccount();

​
refetch()

Manually refetches the session data from the server. 
const { refetch } = useSession();

// Refetch session
await refetch();

​
Session Object Structure

The session object contains the following structure: 
interface Session {
  user: User;
  active_signin: ActiveSignin;
  signin_attempts: SigninAttempt[];
  signup_attempts: SignupAttempt[];
  organization_memberships: OrganizationMembership[];
  workspace_memberships: WorkspaceMembership[];
}

​
Examples

​
Conditional Rendering Based on Authentication

function AuthenticatedContent() {
  const { session, loading } = useSession();

  if (loading) {
    return <div>Loading...</div>;
  }

  return session ? (
    <div>Authenticated content</div>
  ) : (
    <div>Please sign in</div>
  );
}

​
Organization Switching

function OrganizationSwitcher() {
  const { session, switchOrganization } = useSession();
  
  const organizations = session?.organization_memberships || [];

  return (
    <select onChange={(e) => switchOrganization(e.target.value)}>
      <option value="">Personal</option>
      {organizations.map((membership) => (
        <option key={membership.id} value={membership.organization.id}>
          {membership.organization.name}
        </option>
      ))}
    </select>
  );
}

​
Token Usage for API Calls

function ApiExample() {
  const { getToken } = useSession();

  const callAPI = async () => {
    const token = await getToken();
    
    const response = await fetch('/api/protected', {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    
    return response.json();
  };

  return (
    <button onClick={callAPI}>
      Call Protected API
    </button>
  );
}

​
Notes

  • The session automatically refreshes every 30 seconds to stay up-to-date
  • Token caching is handled automatically to avoid unnecessary API calls
  • In staging mode, development session tokens are managed automatically
  • Session switching operations automatically update the session state