Client API

createAuthClient(config)

Factory function that creates an AuthClient instance.

import { createAuthClient } from 'authfort-client';

const auth = createAuthClient({
  baseUrl: '/auth',
  tokenMode: 'cookie',
});

import { createAuthClient } from 'authfort-client';

const auth = createAuthClient({
  baseUrl: '/auth',
  tokenMode: 'cookie',
});

AuthClientConfig

Field	Type	Default	Description
baseUrl	string	— (required)	Auth server base URL
tokenMode	'cookie' | 'bearer'	'cookie'	Token delivery mode
refreshBuffer	number	30	Seconds before expiry to trigger refresh
tokenStorage	TokenStorage	—	Required for bearer mode

TokenStorage

interface TokenStorage {
  get(): Promise<string | null>;
  set(token: string): Promise<void>;
  clear(): Promise<void>;
}

interface TokenStorage {
  get(): Promise<string | null>;
  set(token: string): Promise<void>;
  clear(): Promise<void>;
}

---

AuthClient Methods

initialize()

Check for an existing session on startup.

Returns: Promise<void>

signUp(data)

Create a new user account.

Param	Type	Description
data.email	string	User email
data.password	string	Password
data.name	string?	Display name
data.avatarUrl	string?	Profile image URL
data.phone	string?	Phone number

Returns: Promise<AuthUser> Throws: AuthClientError

signIn(data)

Authenticate with email and password.

Param	Type	Description
data.email	string	User email
data.password	string	Password

Returns: Promise<AuthUser> Throws: AuthClientError

signInWithProvider(provider, options?)

Start OAuth flow. In redirect mode (default), navigates the browser. In popup mode, opens a popup window and returns a promise.

Param	Type	Description
provider	OAuthProvider	Provider name — built-in ('google', 'github') or any generic provider string
options	OAuthSignInOptions?	OAuth flow options

Returns: void (redirect mode) or Promise<AuthUser> (popup mode)

signOut()

Revoke the refresh token and clear auth state.

Returns: Promise<void>

getUser()

Get the current user from the server.

Returns: Promise<AuthUser> Throws: AuthClientError if not authenticated

getToken()

Get a valid access token. Refreshes automatically if expired.

Returns: Promise<string | null> — null in cookie mode

fetch(url, options?)

Make an authenticated request. Retries once on 401.

Param	Type	Description
url	string	Request URL
options	RequestInit?	Standard fetch options

Returns: Promise<Response>

onAuthStateChange(callback)

Listen for auth state changes.

Param	Type	Description
callback	(state: AuthState, user: AuthUser | null) => void	State change handler

Returns: () => void — unsubscribe function

requestMagicLink(email)

Request a magic link for passwordless login.

Param	Type	Description
email	string	User email

Returns: Promise<void> Throws: AuthClientError

verifyMagicLink(token)

Verify a magic link token and log in.

Param	Type	Description
token	string	Magic link token

Returns: Promise<AuthUser> Throws: AuthClientError

requestOTP(email)

Request an email OTP code for passwordless login.

Param	Type	Description
email	string	User email

Returns: Promise<void> Throws: AuthClientError

verifyOTP(email, code)

Verify an email OTP code and log in.

Param	Type	Description
email	string	User email
code	string	6-digit OTP code

Returns: Promise<AuthUser> Throws: AuthClientError

verifyEmail(token)

Verify email address with a verification token.

Param	Type	Description
token	string	Verification token

Returns: Promise<void> Throws: AuthClientError

---

Types

AuthUser

interface AuthUser {
  id: string;
  email: string;
  name?: string;
  phone?: string;
  roles: string[];
  emailVerified: boolean;
  avatarUrl?: string;
  createdAt: string;
}

interface AuthUser {
  id: string;
  email: string;
  name?: string;
  phone?: string;
  roles: string[];
  emailVerified: boolean;
  avatarUrl?: string;
  createdAt: string;
}

AuthState

type AuthState = 'authenticated' | 'unauthenticated' | 'loading';

type AuthState = 'authenticated' | 'unauthenticated' | 'loading';

OAuthProvider

type OAuthProvider = 'google' | 'github' | (string & {});

type OAuthProvider = 'google' | 'github' | (string & {});

OAuthSignInOptions

interface OAuthSignInOptions {
  /** OAuth flow mode. 'redirect' (default) or 'popup'. */
  mode?: 'redirect' | 'popup';
  /** URL path to redirect to after auth (relative path starting with "/"). Only used in redirect mode. */
  redirectTo?: string;
}

interface OAuthSignInOptions {
  /** OAuth flow mode. 'redirect' (default) or 'popup'. */
  mode?: 'redirect' | 'popup';
  /** URL path to redirect to after auth (relative path starting with "/"). Only used in redirect mode. */
  redirectTo?: string;
}

AuthClientError

class AuthClientError extends Error {
  message: string;
  code: string;
  statusCode: number;
}

class AuthClientError extends Error {
  message: string;
  code: string;
  statusCode: number;
}

---

Framework Integrations

React

import { AuthProvider, useAuth } from 'authfort-client/react';

import { AuthProvider, useAuth } from 'authfort-client/react';

Export	Description
AuthProvider	Context provider component. Props: client: AuthClient. Auto-calls initialize().
useAuth()	Hook returning { state, user, isAuthenticated, isLoading, client }

Vue

import { provideAuth, useAuth } from 'authfort-client/vue';

import { provideAuth, useAuth } from 'authfort-client/vue';

Export	Description
provideAuth(client)	Provide auth to component tree. Auto-calls initialize().
useAuth()	Composable returning { state, user, isAuthenticated, isLoading, client }

Svelte

import { createAuthStore } from 'authfort-client/svelte';

import { createAuthStore } from 'authfort-client/svelte';

Export	Description
createAuthStore(client)	Returns { state, user, isAuthenticated, isLoading, client } as Svelte stores. Auto-calls initialize().