JavaScript (client)

Installation

@niledatabase/client provides client-side functions for managing authentication, sessions, and user accounts. It is designed to work seamlessly with @niledatabase/server which provides the server-side routes.

npm install @niledatabase/client

Usage

The library exports a singleton instance of the Authorizer class, named auth, which is pre-configured for most use cases.

import { auth } from '@niledatabase/client';

Authentication

Signs in a user. Supports both credentials (email/password) and Single Sign-On (SSO) providers.

// Email and password
await auth.signIn('credentials', {
  email: 'user@example.com',
  password: 'password',
});

// Single Sign-On (Google, GitHub, etc.)
await auth.signIn('google', { callbackUrl: '/dashboard' });

Parameters

Name	Type	Description
`provider`	`string`	The authentication provider (e.g., `'credentials'`, `'google'`, `'github'`).
`options`	`object`	Configuration options.

Options:

Name	Type	Description
`email`	`string`	User’s email (required for `'credentials'`).
`password`	`string`	User’s password (required for `'credentials'`).
`callbackUrl`	`string`	URL to redirect to after successful sign-in.
`redirect`	`boolean`	If `false`, prevents automatic redirection (useful for handling responses manually).

Creates a new user account. Can optionally create a new tenant for the user.

await auth.signUp({
  email: 'user@example.com',
  password: 'password',
  createTenant: true, // Creates a tenant with the user's email as the name
});

Parameters

Name	Type	Description
`options`	`object`	Sign-up configuration.

Options:

Name	Type	Description
`email`	`string`	User’s email address.
`password`	`string`	User’s password.
`createTenant`	`boolean \| string`	If `true`, creates a tenant named after the user’s email. If a string, creates a tenant with that specific name.
`callbackUrl`	`string`	URL to redirect to after successful sign-up.

signOut

Logs the current user out and clears the session.

await auth.signOut({ callbackUrl: '/goodbye' });

Parameters

Name	Type	Description
`options`	`object`	Sign-out configuration.

Options:

Name	Type	Description
`callbackUrl`	`string`	URL to redirect to after sign-out.

Session Management

getSession

Retrieves the current user session. If a valid session is cached, it is returned; otherwise, a request is made to the server.

const session = await auth.getSession();
if (session.user) {
  console.log('User is logged in:', session.user);
}

Password Management

resetPassword

Initiates a password reset flow (typically by sending a reset email).

await auth.resetPassword({
  email: 'user@example.com',
  password: 'new-pass', // Optional: if setting a new password directly
});

Multi-factor Authentication

mfa

Manages Multi-Factor Authentication (MFA) flows, including setup, challenge verification, and removal. The User object in the session includes a multiFactor property indicating if MFA is enabled.

import { mfa } from '@niledatabase/client';
// or
// await auth.mfa({ ... });

Parameters

mfa(params: MfaParams) automatically selects the HTTP verb based on the payload.

Name	Type	Default	Description
`method`	`'authenticator' \| 'email'`	`'authenticator'`	MFA method to target.
`scope`	`'setup' \| 'challenge'`	`'challenge'`	The operation scope.
`token`	`string`	`undefined`	Challenge token (required for verification and some disable flows).
`code`	`string`	`undefined`	6-digit verification code or recovery code.
`remove`	`boolean`	`false`	If `true`, disables MFA for the specified method.

Examples

// 1. Start Setup
// Returns a payload with secret/otpauthUrl (for QR) or triggers an email code
const setup = await auth.mfa({ method: 'authenticator', scope: 'setup' });

// 2. Verify Challenge
// Use the token from setup or login challenge, and the user's code
const verified = await auth.mfa({
  token: setup.token,
  code: '123456',
  method: setup.method,
  scope: 'challenge',
});

// 3. Disable MFA
await auth.mfa({ method: 'authenticator', remove: true });

// 4. Handle Login Challenge
const challenge = await auth.signIn('credentials', { email, password });

// If MFA is required, the response contains a token
if (challenge && typeof challenge === 'object' && 'token' in challenge) {
  const result = await auth.mfa({
    token: String(challenge.token),
    code: '654321', // Code input by user
    method: challenge.method ?? 'authenticator',
    scope: 'challenge',
  });
  if (!result?.ok) throw new Error('MFA verification failed');
}

Error Handling

Non-200 responses may return a ChallengeRedirect object ({ url: string }) with an error query parameter. Parse this parameter to display user-friendly error messages.

Utilities

getCsrfToken

Retrieves a CSRF token for form submissions.

const token = await auth.getCsrfToken();
// Optional: Fetch from custom URL
const customToken = await auth.getCsrfToken('/api/auth/custom-csrf');

getProviders

Retrieves the list of configured authentication providers.

const providers = await auth.getProviders();

Advanced Configuration

Custom Authorizer

For advanced use cases, such as connecting to a different API endpoint or managing multiple auth contexts, you can create a custom instance of Authorizer.

import { Authorizer } from '@niledatabase/client';

const customAuth = new Authorizer({
  baseUrl: 'https://api.myapp.com',
  basePath: '/auth',
});

Constructor Options

Name	Type	Description
`baseUrl`	`string`	The base URL of the API.
`basePath`	`string`	Path to auth endpoints (default: `/api`).
`init`	`RequestInit`	Default fetch options for all requests.

The instance exposes a state object with baseUrl, session, and loading status. Configuration can be updated later via auth.configure({ ... }).

Nile Auth

Frameworks

Installation

Usage

Authentication

Parameters

Parameters

signOut

Parameters

Session Management

getSession

Password Management

resetPassword

Multi-factor Authentication

mfa

Parameters

Examples

Error Handling

Utilities

getCsrfToken

getProviders

Advanced Configuration

Custom Authorizer

Constructor Options

​Installation

​Usage

​Authentication

​signIn

​Parameters

​signUp

​Parameters

​signOut

​Parameters

​Session Management

​getSession

​Password Management

​resetPassword

​Multi-factor Authentication

​mfa

​Parameters

​Examples

​Error Handling

​Utilities

​getCsrfToken

​getProviders

​Advanced Configuration

​Custom Authorizer

​Constructor Options

Installation

Usage

Authentication

signIn

Parameters

signUp

Parameters

signOut

Parameters

Session Management

getSession

Password Management

resetPassword

Multi-factor Authentication

mfa

Parameters

Examples

Error Handling

Utilities

getCsrfToken

getProviders

Advanced Configuration

Custom Authorizer

Constructor Options