Skip to main content

​
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: '[email protected]',
  password: 'password',
});

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

​
Parameters

NameTypeDescription
providerstringThe authentication provider (e.g., 'credentials', 'google', 'github').
optionsobjectConfiguration options.
Options:
NameTypeDescription
emailstringUser’s email (required for 'credentials').
passwordstringUser’s password (required for 'credentials').
callbackUrlstringURL to redirect to after successful sign-in.
redirectbooleanIf 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: '[email protected]',
  password: 'password',
  createTenant: true, // Creates a tenant with the user's email as the name
});

​
Parameters

NameTypeDescription
optionsobjectSign-up configuration.
Options:
NameTypeDescription
emailstringUser’s email address.
passwordstringUser’s password.
createTenantboolean | stringIf true, creates a tenant named after the user’s email. If a string, creates a tenant with that specific name.
callbackUrlstringURL to redirect to after successful sign-up.

​
signOut

Logs the current user out and clears the session. 
await auth.signOut({ callbackUrl: '/goodbye' });

​
Parameters

NameTypeDescription
optionsobjectSign-out configuration.
Options:
NameTypeDescription
callbackUrlstringURL 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: '[email protected]',
  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.
NameTypeDefaultDescription
method'authenticator' | 'email''authenticator'MFA method to target.
scope'setup' | 'challenge''challenge'The operation scope.
tokenstringundefinedChallenge token (required for verification and some disable flows).
codestringundefined6-digit verification code or recovery code.
removebooleanfalseIf 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' });

​
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

NameTypeDescription
baseUrlstringThe base URL of the API.
basePathstringPath to auth endpoints (default: /api).
initRequestInitDefault 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({ ... }).