JavaScript (client)

Use the Authorizer class from @niledatabase/client to manage authentication

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

signIn

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

// Email and password
await auth.signIn('credentials', {
  email: '[e-mail]',
  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).

signUp

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

await auth.signUp({
  email: '[e-mail]',
  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: '[e-mail]',
  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

setup

// 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' });

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({ ... }).