​
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

HeaderDescriptionWhen to Use
AuthorizationBearer <token>Required for all authenticated endpoints except login and self-registration
X-Device-IDUnique device identifierRequired for all authentication requests
The Authorization header is not needed for /v1/authenticate since this endpoint issues the token.