Authentication overview

Overview

The Authentication API provides secure user authentication with support for:

Username/password authentication
Multi-factor authentication (2FA)
JWT token management
API key authentication

Authentication Flow

1. Initial Authentication

POST /v1/authenticate
Content-Type: application/json

{
  "username": "user@example.com",
  "password": "secure_password"
}

Response Options: a) Direct Authentication Success:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 900,
  "user_id": "123e4567-e89b-12d3-a456-426614174000"
}

b) When MFA is required:

{
  "credential_type": "phone",
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "message": "An OTP has been sent to your phone successfully."
}

2. Verify 2FA (if required)

POST /v1/verify-2fa
Content-Type: application/json

{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "otp": "123456"
}

Token Management

Access Token: 15-minute lifespan, sent in Authorization header
Refresh Token: 14-day lifespan, stored as HTTP-only cookie
Token Format: Authorization: Bearer <token>

Refresh Access Token

POST /v1/refresh-token
X-Device-ID: 16be137a-f9b1-4830-8828-f5a51038918e

Security Features

Brute force protection
IP-based rate limiting
Device tracking
Secure token rotation
HTTP-only cookies for refresh tokens

Required Headers

Header	Description	When to Use
Authorization	`Bearer <token>`	Required for all authenticated endpoints except login and self-registration
X-Device-ID	Unique device identifier	Required for all authentication requests

The Authorization header is not needed for /v1/authenticate since this endpoint issues the token.

Set Primary Address Login

API Documentation

Addresses

Authentication

Users

Roles

Personas

Customers

Countries

Currencies

FX

Ledger

Tariffs

Health

Tasks

Transactions

Uploads

Invoices

Accounts

Chat

Utilities

Profile

KYB

RBAC

Authentication overview

Overview

Authentication Flow

1. Initial Authentication

2. Verify 2FA (if required)

Token Management

Refresh Access Token

Security Features

Required Headers

​Overview

​Authentication Flow

​1. Initial Authentication

​2. Verify 2FA (if required)

​Token Management

​Refresh Access Token

​Security Features

​Required Headers

Overview

Authentication Flow

1. Initial Authentication

2. Verify 2FA (if required)

Token Management

Refresh Access Token

Security Features

Required Headers