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

# Authentication & User Management

> Manage login sessions, user accounts, and role assignments

## Overview

The Authentication module handles identity verification for all users and provides user lifecycle management within your tenant. Every API call (except login) requires a valid Bearer token in the `Authorization` header.

## Common Workflows

**New team member onboarding:** A `BANK_ADMIN` creates a user account → The new user receives a welcome email → They log in and begin using the dashboard.

**Session refresh:** When your access token expires (every 15 minutes), use the refresh token to obtain a new pair without prompting for credentials again.

## Permissions

| Action                                 | Who Can Do It |
| -------------------------------------- | ------------- |
| Login, refresh token, view own profile | Anyone        |
| List, create, update, deactivate users | `BANK_ADMIN`  |

## Endpoints

| Method   | Endpoint                 | Description                                 |
| -------- | ------------------------ | ------------------------------------------- |
| `POST`   | `/api/v1/auth/login`     | Authenticate and receive tokens             |
| `POST`   | `/api/v1/auth/refresh`   | Exchange refresh token for new access token |
| `GET`    | `/api/v1/auth/me`        | Retrieve current user profile               |
| `GET`    | `/api/v1/auth/users`     | List all users in tenant                    |
| `POST`   | `/api/v1/auth/users`     | Create a new user                           |
| `PATCH`  | `/api/v1/auth/users/:id` | Update user details or role                 |
| `DELETE` | `/api/v1/auth/users/:id` | Deactivate a user                           |

***

### Login

Authenticate with email and password to receive an access token and refresh token.

**Request Body**

| Field      | Type     | Required | Description             |
| ---------- | -------- | -------- | ----------------------- |
| `email`    | `string` | ✅        | User's registered email |
| `password` | `string` | ✅        | User's password         |

**Example Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST /v1/auth/login \
    -H "Content-Type: application/json" \
    -d '{
      "email": "analyst@bank.com",
      "password": "SecurePass123!"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("/v1/auth/login", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      email: "analyst@bank.com",
      password: "SecurePass123!",
    }),
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "/v1/auth/login",
      headers={"Content-Type": "application/json"},
      json={
          "email": "analyst@bank.com",
          "password": "SecurePass123!"
      }
  )
  data = response.json()
  ```
</CodeGroup>

**Example Response -200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}
```

**Example Response -401 Unauthorized**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Email or password is incorrect"
  }
}
```

***

### Refresh Token

Obtain a new access token without re-entering credentials.

**Request Body**

| Field          | Type     | Required | Description                  |
| -------------- | -------- | -------- | ---------------------------- |
| `refreshToken` | `string` | ✅        | The refresh token from login |

**Example Request**

```bash theme={null}
curl -X POST /v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "eyJhbG..." }'
```

**Example Response -200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}
```

<Note>
  Access tokens expire after **15 minutes** (`expiresIn: 900`). Refresh tokens
  expire after **7 days**.
</Note>

***

### Get My Profile

Retrieve the currently authenticated user's details, including their tenant.

**Example Request**

```bash theme={null}
curl -X GET /v1/auth/me \
  -H "Authorization: Bearer <access_token>"
```

**Example Response -200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "analyst@bank.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "ANALYST",
    "isActive": true,
    "lastLoginAt": "2026-05-16T10:00:00Z",
    "createdAt": "2026-01-15T09:30:00Z",
    "tenant": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "First Bank of Nigeria",
      "slug": "first-bank",
      "logoUrl": null,
      "primaryColor": "#0F172A"
    }
  }
}
```

***

### List Users

Retrieve all users within your tenant.

**Query Parameters**

| Parameter | Type      | Default | Description              |
| --------- | --------- | ------- | ------------------------ |
| `page`    | `integer` | `1`     | Page number              |
| `limit`   | `integer` | `50`    | Items per page (max 100) |
| `role`    | `string`  | -       | Filter by role           |

**Example Request**

```bash theme={null}
curl -X GET "/v1/auth/users?page=1&limit=10" \
  -H "Authorization: Bearer <access_token>"
```

**Example Response -200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "email": "analyst@bank.com",
        "firstName": "Jane",
        "lastName": "Smith",
        "role": "ANALYST",
        "isActive": true,
        "lastLoginAt": "2026-05-16T10:00:00Z",
        "createdAt": "2026-01-15T09:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}
```

***

### Create User

Add a new user to your tenant. The new user will receive a welcome email with login instructions.

**Request Body**

| Field       | Type     | Required | Description                                                 |
| ----------- | -------- | -------- | ----------------------------------------------------------- |
| `email`     | `string` | ✅        | Unique email address                                        |
| `password`  | `string` | ✅        | Minimum 8 characters                                        |
| `firstName` | `string` | ✅        | First name                                                  |
| `lastName`  | `string` | ✅        | Last name                                                   |
| `role`      | `string` | ✅        | `BANK_ADMIN`, `COMPLIANCE_OFFICER`, `ANALYST`, or `AUDITOR` |

**Example Request**

```bash theme={null}
curl -X POST /v1/auth/users \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "new.officer@bank.com",
    "password": "SecurePass123!",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "COMPLIANCE_OFFICER"
  }'
```

**Example Response -201 Created**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "email": "new.officer@bank.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "COMPLIANCE_OFFICER",
    "isActive": true,
    "lastLoginAt": null,
    "createdAt": "2026-05-16T14:20:00Z"
  }
}
```

**Example Response -409 Conflict**

```json theme={null}
{
  "success": false,
  "error": {
    "code": "USER_ALREADY_EXISTS",
    "message": "A user with this email already exists"
  }
}
```

***

### Update User

Modify a user's details or role.

**Path Parameters**

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `id`      | `string` | User UUID   |

**Request Body**

All fields are optional.

| Field       | Type      | Description            |
| ----------- | --------- | ---------------------- |
| `firstName` | `string`  | Updated first name     |
| `lastName`  | `string`  | Updated last name      |
| `role`      | `string`  | New role assignment    |
| `isActive`  | `boolean` | Activate or deactivate |

**Example Request**

```bash theme={null}
curl -X PATCH /v1/auth/users/770e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "ANALYST",
    "isActive": true
  }'
```

**Example Response -200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "email": "new.officer@bank.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "ANALYST",
    "isActive": true,
    "lastLoginAt": null,
    "createdAt": "2026-05-16T14:20:00Z"
  }
}
```

***

### Deactivate User

Soft-delete a user by deactivating their account.

**Path Parameters**

| Parameter | Type     | Description |
| --------- | -------- | ----------- |
| `id`      | `string` | User UUID   |

**Example Request**

```bash theme={null}
curl -X DELETE /v1/auth/users/770e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer <access_token>"
```

**Example Response -200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "email": "new.officer@bank.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "role": "ANALYST",
    "isActive": false,
    "lastLoginAt": null,
    "createdAt": "2026-05-16T14:20:00Z"
  }
}
```

<Warning>
  Deactivated users cannot log in but their audit history and case contributions
  are preserved for compliance.
</Warning>