Authentication

All authentication methods update the auth state automatically. After a successful sign in or sign up, the state changes to 'authenticated' and any listeners are notified.

Sign Up

const user = await auth.signUp({
  email: 'user@example.com',
  password: 'strongpassword',
  name: 'Jane Doe', // optional
});

console.log(user.id);    // "uuid-string"
console.log(user.email); // "user@example.com"
console.log(user.roles); // []

const user = await auth.signUp({
  email: 'user@example.com',
  password: 'strongpassword',
  name: 'Jane Doe', // optional
});

console.log(user.id);    // "uuid-string"
console.log(user.email); // "user@example.com"
console.log(user.roles); // []

After signup, the user is automatically signed in and the auth state changes to 'authenticated'.

Sign In

const user = await auth.signIn({
  email: 'user@example.com',
  password: 'strongpassword',
});

const user = await auth.signIn({
  email: 'user@example.com',
  password: 'strongpassword',
});

Sign Out

await auth.signOut();

await auth.signOut();

Revokes the refresh token and clears auth state. In bearer mode, also clears the stored token.

OAuth

Redirect the user to the OAuth provider:

// Redirect mode (default)
auth.signInWithProvider('google');
// or
auth.signInWithProvider('github');

// Redirect mode (default)
auth.signInWithProvider('google');
// or
auth.signInWithProvider('github');

This navigates the browser to /auth/oauth/{provider}/authorize. After the OAuth flow completes, the user is redirected back to your app with auth cookies set.

Popup Mode

Use popup mode to avoid a full-page redirect. The client opens a popup window for the OAuth flow and resolves a promise when auth completes:

// Popup mode — opens a window, returns a promise
const user = await auth.signInWithProvider('google', { mode: 'popup' });
console.log(user.email);

// Popup mode — opens a window, returns a promise
const user = await auth.signInWithProvider('google', { mode: 'popup' });
console.log(user.email);

Redirect To

Specify where to land after OAuth completes:

// Redirect to a specific page after OAuth
auth.signInWithProvider('google', { redirectTo: '/dashboard' });

// Redirect to a specific page after OAuth
auth.signInWithProvider('google', { redirectTo: '/dashboard' });

The redirectTo path must be relative (start with /). Framework integrations (React, Vue, Svelte) call initialize() automatically, so there’s no need to call it manually on the landing page.

Passwordless

Magic Link

Request a magic link and verify when the user clicks the link in their email:

// Request magic link
await auth.requestMagicLink('user@example.com');

// After user clicks the link in their email, extract the token and verify
const user = await auth.verifyMagicLink(token);

// Request magic link
await auth.requestMagicLink('user@example.com');

// After user clicks the link in their email, extract the token and verify
const user = await auth.verifyMagicLink(token);

The server always returns success for requestMagicLink() even if the email doesn’t exist, to prevent user enumeration.

Email OTP

Request a 6-digit code and verify when the user enters it:

// Request OTP code
await auth.requestOTP('user@example.com');

// After user enters the code
const user = await auth.verifyOTP('user@example.com', '847291');

// Request OTP code
await auth.requestOTP('user@example.com');

// After user enters the code
const user = await auth.verifyOTP('user@example.com', '847291');

Email Verification

Verify a user’s email address using a verification token:

// Verify email with token from verification email
await auth.verifyEmail(token);

// Verify email with token from verification email
await auth.verifyEmail(token);

After calling verifyEmail(), the client automatically updates the local user state to reflect emailVerified: true.

Get Current User

const user = await auth.getUser();

const user = await auth.getUser();

Returns the current user from the server (calls /auth/me).

Error Handling

All methods throw AuthClientError on failure:

import { AuthClientError } from 'authfort-client';

try {
  await auth.signIn({ email: 'user@example.com', password: 'wrong' });
} catch (error) {
  if (error instanceof AuthClientError) {
    console.log(error.message);    // "Invalid credentials"
    console.log(error.code);       // "invalid_credentials"
    console.log(error.statusCode); // 401
  }
}

import { AuthClientError } from 'authfort-client';

try {
  await auth.signIn({ email: 'user@example.com', password: 'wrong' });
} catch (error) {
  if (error instanceof AuthClientError) {
    console.log(error.message);    // "Invalid credentials"
    console.log(error.code);       // "invalid_credentials"
    console.log(error.statusCode); // 401
  }
}

Code	Meaning
invalid_credentials	Wrong email or password
user_exists	Email already registered
oauth_account	Account uses social login (includes providers list)
signup_disabled	Public signup is disabled
user_banned	Account is banned