Client API

Complete reference for client-side authentication helpers — sign-in, sign-out, sessions, and multi-account switching.

All client helpers are exported from @robojs/auth/client and re-exported from the main @robojs/auth entry. Each function accepts optional ClientOptions for customizing the base path, base URL, headers, or fetch implementation.

ClientOptions

Shared configuration object accepted by all client helpers.

interface ClientOptions {
  basePath?: string   // Default: '/api/auth'
  baseUrl?: string    // Default: '' (same origin)
  fetch?: typeof fetch // Custom fetch implementation
  headers?: Record<string, string> // Extra headers
}

Use these options when working with cross-origin auth servers, server-side rendering, or custom fetch implementations.

Signs in with the specified provider.

// Legacy mode
function signIn(
  providerId: string,
  body?: Record<string, unknown>,
  options?: ClientOptions
): Promise<Response>

// Redirect-aware mode
function signIn(
  providerId: string,
  options?: { csrfToken?: string; callbackUrl?: string; [key: string]: unknown },
  proxy?: ClientOptions,
  redirect?: boolean | 'manual'
): Promise<SignInResult>

// Legacy mode
function signIn(
  providerId: string,
  body?: Record<string, unknown>,
  options?: ClientOptions
): Promise<Response>

// Redirect-aware mode
function signIn(
  providerId: string,
  options?: { csrfToken?: string; callbackUrl?: string; [key: string]: unknown },
  proxy?: ClientOptions,
  redirect?: boolean | 'manual'
): Promise<SignInResult>

Parameters:

Parameter	Type	Description
`providerId`	`string`	Provider ID (e.g., `'discord'`, `'google'`, `'credentials'`)
`body` / `options`	`Record<string, unknown>`	Extra payload — email, password, callbackUrl, csrfToken
`options` / `proxy`	`ClientOptions`	Base URL, headers, custom fetch
`redirect`	`boolean \| 'manual'`	Redirect behavior (see below)

Redirect modes:

Value	Behavior	Return type
`true`	Creates hidden form and submits (POST with CSRF)	`{ ok: true, redirected: true }`
`'manual'`	Returns the redirect URL without navigating	`{ ok: true, url: string }`
`false`	Fetch-based flow with normalized result	`{ ok: boolean, url?: string, error?: string }`
omitted	Legacy behavior — returns raw `Response`	`Response`

Examples:

import { signIn } from '@robojs/auth/client'

// OAuth sign-in (redirects to provider)
await signIn('discord')

// Email/password sign-in
await signIn('credentials', { email: 'user@example.com', password: 'pass' })

// With callback URL
await signIn('discord', { callbackUrl: '/dashboard' })

// Cross-origin redirect (form-based)
await signIn('discord', { callbackUrl: '/dashboard' }, { baseUrl: 'https://auth.example.com' }, true)

// Manual redirect (get URL only)
const { url } = await signIn('discord', { callbackUrl: '/' }, { baseUrl: process.env.AUTH_URL! }, 'manual')

import { signIn } from '@robojs/auth/client'

// OAuth sign-in (redirects to provider)
await signIn('discord')

// Email/password sign-in
await signIn('credentials', { email: 'user@example.com', password: 'pass' })

// With callback URL
await signIn('discord', { callbackUrl: '/dashboard' })

// Cross-origin redirect (form-based)
await signIn('discord', { callbackUrl: '/dashboard' }, { baseUrl: 'https://auth.example.com' }, true)

// Manual redirect (get URL only)
const { url } = await signIn('discord', { callbackUrl: '/' }, { baseUrl: process.env.AUTH_URL! }, 'manual')

signOut

Signs out and clears the session cookie.

function signOut(options?: ClientOptions): Promise<Response>

function signOut(
  options?: { csrfToken?: string; callbackUrl?: string },
  proxy?: ClientOptions,
  redirect?: boolean | 'manual'
): Promise<SignOutResult>

function signOut(options?: ClientOptions): Promise<Response>

function signOut(
  options?: { csrfToken?: string; callbackUrl?: string },
  proxy?: ClientOptions,
  redirect?: boolean | 'manual'
): Promise<SignOutResult>

Auto-fetches CSRF token via getCsrfToken.

Example:

import { signOut } from '@robojs/auth/client'

await signOut()

// With redirect
await signOut({ callbackUrl: '/' }, { baseUrl: 'https://auth.example.com' }, true)

import { signOut } from '@robojs/auth/client'

await signOut()

// With redirect
await signOut({ callbackUrl: '/' }, { baseUrl: 'https://auth.example.com' }, true)

Registers a new user via the email/password signup endpoint.

function signUp(
  body: Record<string, unknown>,
  options?: ClientOptions
): Promise<Response>

function signUp(
  body: Record<string, unknown>,
  options?: ClientOptions
): Promise<Response>

Parameters:

Field	Type	Required	Description
`email`	`string`	Yes	User email
`password`	`string`	Yes	Password (min 8 chars)
`confirmPassword`	`string`	No	Must match password if provided
`name`	`string`	No	Display name
`acceptTerms`	`boolean`	No	Terms acceptance

Auto-fetches CSRF token. On success, the user is auto-signed in.

Example:

import { signUp } from '@robojs/auth/client'

const response = await signUp({
  email: 'user@example.com',
  password: 'securepassword',
  confirmPassword: 'securepassword',
  name: 'Jane Doe'
})

import { signUp } from '@robojs/auth/client'

const response = await signUp({
  email: 'user@example.com',
  password: 'securepassword',
  confirmPassword: 'securepassword',
  name: 'Jane Doe'
})

getSession

Returns the current session or null.

function getSession<T extends Session = Session>(
  options?: ClientOptions
): Promise<T | null>

function getSession(
  options?: ClientOptions
): Promise<T | null>

Example:

import { getSession } from '@robojs/auth/client'

const session = await getSession()
if (session) {
  console.log(session.user?.name)
}

// With custom headers (e.g., forwarding cookies in SSR)
const session = await getSession({
  headers: { cookie: request.headers.get('cookie') ?? '' }
})

import { getSession } from '@robojs/auth/client'

const session = await getSession()
if (session) {
  console.log(session.user?.name)
}

// With custom headers (e.g., forwarding cookies in SSR)
const session = await getSession({
  headers: { cookie: request.headers.get('cookie') ?? '' }
})

getProviders

Lists configured auth providers.

function getProviders(
  options?: ClientOptions
): Promise<PublicProvider[] | null>

function getProviders(
  options?: ClientOptions
): Promise<PublicProvider[] | null>

Example:

import { getProviders } from '@robojs/auth/client'

const providers = await getProviders()
// [{ id: 'discord', name: 'Discord', type: 'oauth', ... }]

import { getProviders } from '@robojs/auth/client'

const providers = await getProviders()
// [{ id: 'discord', name: 'Discord', type: 'oauth', ... }]

getCsrfToken

Retrieves a CSRF token for form submissions.

function getCsrfToken(
  options?: ClientOptions
): Promise<string | null>

function getCsrfToken(
  options?: ClientOptions
): Promise<string | null>

Most helpers auto-fetch the CSRF token, so direct usage is rare.

getSessions

Lists all sessions on the current device. Requires database session strategy.

function getSessions(
  options?: ClientOptions
): Promise<DeviceSession[] | null>

function getSessions(
  options?: ClientOptions
): Promise<DeviceSession[] | null>

DeviceSession type:

Field	Type	Description
`userId`	`string`	User ID
`name`	`string \| null`	Display name
`email`	`string \| null`	Email address
`image`	`string \| null`	Avatar URL
`isActive`	`boolean`	Currently active session
`isExpired`	`boolean`	Session has expired

Example:

import { getSessions } from '@robojs/auth/client'

const sessions = await getSessions()
const active = sessions?.find(s => s.isActive)

import { getSessions } from '@robojs/auth/client'

const sessions = await getSessions()
const active = sessions?.find(s => s.isActive)

switchSession

Switches the active session to a different user on the device. Requires database strategy.

function switchSession(
  userId: string,
  options?: ClientOptions
): Promise<SwitchSessionResult>

function switchSession(
  userId: string,
  options?: ClientOptions
): Promise<SwitchSessionResult>

SwitchSessionResult:

Field	Type	Description
`ok`	`boolean`	Whether the switch succeeded
`session`	`Session \| undefined`	New active session
`error`	`string \| undefined`	`'session_expired'`, `'not_found'`, or `'forbidden'`

Example:

import { switchSession } from '@robojs/auth/client'

const result = await switchSession('user-id-123')
if (result.ok) {
  console.log('Switched to:', result.session?.user)
}

import { switchSession } from '@robojs/auth/client'

const result = await switchSession('user-id-123')
if (result.ok) {
  console.log('Switched to:', result.session?.user)
}

removeSession

Removes a session from the device stack. If the active session is removed, auto-switches to the most recent valid session.

function removeSession(
  userId: string,
  options?: ClientOptions
): Promise<Response>

function removeSession(
  userId: string,
  options?: ClientOptions
): Promise<Response>

clearSessions

Removes all sessions from the device and signs out.

function clearSessions(
  options?: ClientOptions
): Promise<Response>

function clearSessions(
  options?: ClientOptions
): Promise<Response>

Proxy deployment notes

When using upstream proxy mode or deploying auth to a separate origin, ensure auth server cookies use SameSite=None; Secure for cross-origin, add the frontend origin to the CORS allowlist, and note that the client auto-fetches CSRF tokens before redirects.

Next steps

Server API

Server-side session and token helpers

Sessions

Session strategies and multi-account switching

Email and password

Signup and credential flows

Client API

Server API

Sessions

Email and password

On this page