Skip to main content

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.

​
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

ActionWho Can Do It
Login, refresh token, view own profileAnyone
List, create, update, deactivate usersBANK_ADMIN

​
Endpoints

MethodEndpointDescription
POST/api/v1/auth/loginAuthenticate and receive tokens
POST/api/v1/auth/refreshExchange refresh token for new access token
GET/api/v1/auth/meRetrieve current user profile
GET/api/v1/auth/usersList all users in tenant
POST/api/v1/auth/usersCreate a new user
PATCH/api/v1/auth/users/:idUpdate user details or role
DELETE/api/v1/auth/users/:idDeactivate a user

​
Login

Authenticate with email and password to receive an access token and refresh token. Request Body
FieldTypeRequiredDescription
emailstring✅User’s registered email
passwordstring✅User’s password
Example Request 
curl -X POST /v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "analyst@bank.com",
    "password": "SecurePass123!"
  }'
Example Response — 200 OK 
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}
Example Response — 401 Unauthorized 
{
  "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
FieldTypeRequiredDescription
refreshTokenstring✅The refresh token from login
Example Request 
curl -X POST /v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "eyJhbG..." }'
Example Response — 200 OK 
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}
Access tokens expire after 15 minutes (expiresIn: 900). Refresh tokens expire after 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
ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger50Items per page (max 100)
rolestring—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
FieldTypeRequiredDescription
emailstring✅Unique email address
passwordstring✅Minimum 8 characters
firstNamestring✅First name
lastNamestring✅Last name
rolestring✅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
ParameterTypeDescription
idstringUser UUID
Request Body All fields are optional.
FieldTypeDescription
firstNamestringUpdated first name
lastNamestringUpdated last name
rolestringNew role assignment
isActivebooleanActivate 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
ParameterTypeDescription
idstringUser 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.