> ## Documentation Index
> Fetch the complete documentation index at: https://thenile.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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.

```ts theme={null}
import { auth } from '@niledatabase/client';
```

## Authentication

### signIn

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

```ts theme={null}
// 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). |

### signUp

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

```ts theme={null}
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.

```ts theme={null}
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.

```ts theme={null}
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).

```ts theme={null}
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.

```ts theme={null}
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

```ts setup theme={null}
// 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' });
```

```ts verify theme={null}
// 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',
});
```

```ts disable theme={null}
// 3. Disable MFA
await auth.mfa({ method: 'authenticator', remove: true });
```

```ts challenge theme={null}
// 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.

```ts theme={null}
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.

```ts theme={null}
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`.

```ts theme={null}
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({ ... })`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.