Enable multi-factor authentication

Prerequisites

A valid API key — see Obtain API credentials
An active user account with a verified email address

How MFA works

Paradise Gateway uses email-based OTP for multi-factor authentication. When MFA is enabled for a user, the login flow adds a verification step.

Step 1: Request an OTP challenge

Send POST /v1/mfa/challenges with type: 2fa and the user's email.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/mfa/challenges \
  -H "Content-Type: application/json" \
  -d '{
    "user_name": "john.doe@example.com",
    "type": "2fa"
  }'

Response

A 200 response confirms the OTP was sent.

{
  "status": true,
  "correlation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

The user receives a 6-digit OTP at their registered email address.

Step 2: Verify the OTP

Send POST /v1/mfa/verifications with the OTP the user received.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/mfa/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "user_name": "john.doe@example.com",
    "one_time_password": "123456",
    "user_interface": "api"
  }'

Response example

A 200 response confirms verification and returns the authenticated user and their associated clients.

{
  "status": true,
  "is_client": true,
  "user": {
    "id": "USER-3MtwBwLkdIwHu7ix28a3tqPa",
    "object": "user",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "is_mfa_active": true,
    "is_active": true,
    "is_locked": false
  },
  "clients": [
    {
      "id": "CLIENT-3MtwBwLkdIwHu7ix28a3tqPa",
      "name": "Acme Jewelry",
      "email": "john.doe@example.com",
      "role_id": 1
    }
  ],
  "correlation_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}

Checking MFA status

Retrieve a user to check whether MFA is enabled.

curl https://api.dev.paradisegateway.net/v1/users/USER-3MtwBwLkdIwHu7ix28a3tqPa \
  -H "APIKEY: YOUR-API-KEY"

Look for "is_mfa_active": true in the response.

OTP challenge types

Type	Purpose
`2fa`	Multi-factor authentication during login
`forgot_password`	Password reset — see Reset a user password