Skip to main content
API Preview
Developers

REST API/Authentication

Authentication

User registration, authentication, token management, and multi-factor authentication.

11 endpoints

Endpoints

MethodPathAuth
POST/auth/forgot-password

Request password reset

Public
POST/auth/login

Authenticate user

Public
POST/auth/logout

Logout

Public
GET/auth/me

Get current user

JWT
POST/auth/mfa/authenticate

MFA login verification

Public
POST/auth/mfa/disable

Disable MFA

JWT
POST/auth/mfa/setup

Initiate MFA setup

JWT
POST/auth/mfa/verify

Verify and enable MFA

JWT
POST/auth/refresh

Refresh access token

Public
POST/auth/register

Register a new user

Public
POST/auth/reset-password

Reset password

Public

Endpoint Details

POST /auth/register

POST/auth/registerPublic

Create a new account and return JWT tokens (auto-login). Password must be 12+ characters with uppercase, lowercase, digit, and special character. Argon2id hashing.

Request Example

json
{
  "email": "jane@example.com",
  "password": "S3cure!Pass#2026",
  "role": "member"
}

Response

json
{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
    "email": "jane@example.com",
    "role": "member",
    "created_at": "2026-03-10T08:00:00Z"
  }
}

POST /auth/login

POST/auth/loginPublic

Authenticate with email and password. Returns access token in body (1-hour expiry) and sets refresh token as HttpOnly cookie (7-day expiry). If MFA is enabled, returns mfa_required=true instead of tokens.

Request Example

json
{
  "email": "jane@example.com",
  "password": "S3cure!Pass#2026"
}

Response

json
{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
    "email": "jane@example.com",
    "role": "member",
    "linked_entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "last_login": "2026-03-10T08:30:00Z"
  }
}

POST /auth/refresh

POST/auth/refreshPublic

Refresh the access token using the HttpOnly refresh cookie. Rotates the refresh token (old one is revoked).

Response

json
{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600
}

POST /auth/logout

POST/auth/logoutPublic

Revoke the refresh token and clear the cookie.

GET /auth/me

GET/auth/meJWT

Return the authenticated user profile.

Response

json
{
  "id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
  "email": "jane@example.com",
  "role": "member",
  "linked_entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-03-10T08:00:00Z",
  "last_login": "2026-03-10T08:30:00Z"
}

POST /auth/forgot-password

POST/auth/forgot-passwordPublic

Request a password reset email. Always returns success to prevent user enumeration.

Request Example

json
{
  "email": "jane@example.com"
}

POST /auth/reset-password

POST/auth/reset-passwordPublic

Reset password using a valid reset token. Revokes all existing refresh tokens.

Request Example

json
{
  "token": "abc123def456...",
  "new_password": "N3wS3cure!Pass#2026"
}

POST /auth/mfa/setup

POST/auth/mfa/setupJWT

Generate a new TOTP secret and provisioning URI for authenticator app setup.

POST /auth/mfa/verify

POST/auth/mfa/verifyJWT

Verify a TOTP code and enable MFA. Returns one-time recovery codes.

Request Example

json
{
  "code": "123456"
}

POST /auth/mfa/disable

POST/auth/mfa/disableJWT

Disable MFA for the account. Requires a valid TOTP code.

Request Example

json
{
  "code": "123456"
}

POST /auth/mfa/authenticate

POST/auth/mfa/authenticatePublic

Complete MFA login by providing TOTP code or recovery code. Called after /login returns mfa_required=true.

Request Example

json
{
  "email": "jane@example.com",
  "code": "123456",
  "recovery": false
}