Authentication & User Management

Overview

The Authentication module handles identity verification for all users and provides user lifecycle management within your tenant. Dashboard sessions authenticate with HttpOnly cookies (ratel_access_token, ratel_refresh_token) set by the login endpoint — tokens are never exposed in response bodies. Server-to-server integrations authenticate with an X-API-Key: rk_live_... header, using keys managed via /api/v1/auth/api-keys.

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 cookie expires (every 15 minutes), call the refresh endpoint to rotate the session cookies 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`	Log in — sets session cookies
`POST`	`/api/v1/auth/logout`	Log out and clear the session
`POST`	`/api/v1/auth/refresh`	Rotate the session tokens
`GET`	`/api/v1/auth/me`	Retrieve current user profile
`POST`	`/api/v1/auth/forgot-password`	Request a password reset email
`POST`	`/api/v1/auth/change-password`	Change the current user’s password
`POST`	`/api/v1/auth/mfa/setup`	Begin MFA enrollment
`POST`	`/api/v1/auth/mfa/verify`	Verify an MFA challenge
`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
`GET`	`/api/v1/auth/api-keys`	List server-to-server API keys
`POST`	`/api/v1/auth/api-keys`	Create an API key (`rk_live_...`)
`DELETE`	`/api/v1/auth/api-keys/:id`	Revoke an API key

Authenticate with email and password. On success the API sets two HttpOnly session cookies — ratel_access_token and ratel_refresh_token. Tokens are never returned in the response body. Request Body

Field	Type	Required	Description
`email`	`string`	✅	User’s registered email
`password`	`string`	✅	User’s password

Example Request

curl -X POST /v1/auth/login \
  -H "Content-Type: application/json" \
  -c ratel-cookies.txt \
  -d '{
    "email": "analyst@bank.com",
    "password": "SecurePass123!"
  }'

const response = await fetch("/v1/auth/login", {
  method: "POST",
  credentials: "include", // send/store the session cookies
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "analyst@bank.com",
    password: "SecurePass123!",
  }),
});
const data = await response.json();

import requests

session = requests.Session()  # persists the session cookies
response = session.post(
    "/v1/auth/login",
    headers={"Content-Type": "application/json"},
    json={
        "email": "analyst@bank.com",
        "password": "SecurePass123!"
    }
)
data = response.json()

Example Response -200 OK

{
  "success": true,
  "data": {
    "authenticated": true
  }
}

The session cookies ratel_access_token (15 minutes) and ratel_refresh_token (7 days) are set as HttpOnly Set-Cookie headers. If the tenant’s MFA policy requires it, the response instead carries mfaRequired (or mfaSetupRequired) with a short-lived tempToken for POST /api/v1/auth/mfa/verify or POST /api/v1/auth/mfa/setup.

Example Response -401 Unauthorized

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Email or password is incorrect"
  }
}

Refresh Token

Rotate the session cookies without re-entering credentials. The current ratel_refresh_token cookie is read automatically — no request body is required. Example Request

curl -X POST /v1/auth/refresh \
  -b ratel-cookies.txt \
  -c ratel-cookies.txt

Example Response -200 OK

{
  "success": true,
  "data": {
    "authenticated": true
  }
}

Refreshing rotates both cookies: a fresh ratel_access_token (valid for 15 minutes) and a new ratel_refresh_token (valid for 7 days).

Get My Profile

Retrieve the currently authenticated user’s details, including their tenant. Example Request

curl -X GET /v1/auth/me \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "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

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

Example Response -200 OK

{
  "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

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

{
  "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

{
  "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

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

{
  "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

curl -X DELETE /v1/auth/users/770e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "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"
  }
}

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

Overview

Core Concepts

Features

Modules

API Reference

Authentication & User Management

Overview

Common Workflows

Permissions

Endpoints

Refresh Token

Get My Profile

List Users

Create User

Update User

Deactivate User

​Overview

​Common Workflows

​Permissions

​Endpoints

​Login

​Refresh Token

​Get My Profile

​List Users

​Create User

​Update User

​Deactivate User

Overview

Common Workflows

Permissions

Endpoints

Login

Refresh Token

Get My Profile

List Users

Create User

Update User

Deactivate User