Two-Factor Authentication (2FA)

Manage TOTP-based two-factor authentication for enhanced account security. All endpoints in this section require bearer authentication.

Setup Flow

Setting up 2FA is a two-step process. First, call the setup endpoint to generate a TOTP secret and QR code. Then, after the user configures their authenticator app and enters a valid code, call the enable endpoint to activate 2FA on the account.

Setup TOTP

POST/api/v1/security/totp/setup

Generate a new TOTP secret, QR code URL, and a set of recovery codes. This does not enable 2FA yet -- the user must verify a code first by calling the enable endpoint.

Authentication:Bearer Token

Code Examples

curl -X POST https://api.orbai.world/api/v1/security/totp/setup \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Response

200TOTP setup initiated. Returns the secret, a QR code URL for authenticator apps, and one-time recovery codes.

{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qr_code_url": "otpauth://totp/OrbVPN:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=OrbVPN",
    "recovery_codes": [
      "a1b2c3d4e5",
      "f6g7h8i9j0",
      "k1l2m3n4o5",
      "p6q7r8s9t0",
      "u1v2w3x4y5",
      "z6a7b8c9d0",
      "e1f2g3h4i5",
      "j6k7l8m9n0"
    ]
  }
}

Store Recovery Codes Securely

Recovery codes are shown only once during setup. Prompt the user to save them in a secure location. Each recovery code can only be used once and is intended as a fallback if the user loses access to their authenticator app.

Enable TOTP

POST/api/v1/security/totp/enable

Activate two-factor authentication by verifying a TOTP code from the user's authenticator app. This confirms the user has successfully configured their authenticator.

Authentication:Bearer Token

Request Parameters

Parameter	Type	Required	Description
`code`	string	Required	A 6-digit TOTP code from the user's authenticator app, generated using the secret from the setup step.

Code Examples

curl -X POST https://api.orbai.world/api/v1/security/totp/enable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "482910"
  }'

Responses

200Two-factor authentication enabled successfully.

{
  "success": true,
  "data": {
    "message": "Two-factor authentication has been enabled.",
    "totp_enabled": true
  }
}

400The TOTP code is invalid or has expired.

{
  "success": false,
  "error": {
    "code": "INVALID_TOTP_CODE",
    "message": "The verification code is invalid or has expired. Please try again with a new code."
  }
}

Disable TOTP

POST/api/v1/security/totp/disable

Disable two-factor authentication on the account. Requires a valid TOTP code to confirm the user's identity before disabling.

Authentication:Bearer Token

Request Parameters

Parameter	Type	Required	Description
`code`	string	Required	A 6-digit TOTP code from the user's authenticator app to verify identity before disabling 2FA.

Code Examples

curl -X POST https://api.orbai.world/api/v1/security/totp/disable \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "193847"
  }'

Responses

200Two-factor authentication disabled successfully.

{
  "success": true,
  "data": {
    "message": "Two-factor authentication has been disabled.",
    "totp_enabled": false
  }
}

400The TOTP code is invalid.

{
  "success": false,
  "error": {
    "code": "INVALID_TOTP_CODE",
    "message": "The verification code is invalid or has expired. Please try again with a new code."
  }
}

Regenerate Recovery Codes

POST/api/v1/security/totp/recovery-codes

Generate a new set of recovery codes. All previously issued recovery codes are invalidated. Requires a valid TOTP code for verification.

Authentication:Bearer Token

Request Parameters

Parameter	Type	Required	Description
`totp_code`	string	Required	A 6-digit TOTP code from the user's authenticator app to verify identity.

Code Examples

curl -X POST https://api.orbai.world/api/v1/security/totp/recovery-codes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "totp_code": "571038"
  }'

Responses

200New recovery codes generated. All previous recovery codes are now invalid.

{
  "success": true,
  "data": {
    "recovery_codes": [
      "n1e2w3c4o5",
      "d6e7s8g9e0",
      "n1e2r3a4t5",
      "e6d7c8o9d0",
      "e1s2h3e4r5",
      "e6a7r8e9n0",
      "e1w2a3n4d5",
      "s6a7f8e9r0"
    ],
    "generated_at": "2026-02-08T16:30:00Z"
  }
}

400The TOTP code is invalid.

{
  "success": false,
  "error": {
    "code": "INVALID_TOTP_CODE",
    "message": "The verification code is invalid or has expired. Please try again with a new code."
  }
}

2FA Setup Flow

Call the setup endpoint

POST /api/v1/security/totp/setup returns a TOTP secret, QR code URL, and recovery codes.

Display QR code to user

Show the QR code URL in a QR code image. The user scans it with their authenticator app (Google Authenticator, Authy, 1Password, etc.).

Prompt for verification code

Ask the user to enter the 6-digit code displayed in their authenticator app.

Enable 2FA

POST /api/v1/security/totp/enable with the code. On success, 2FA is now active on the account.

Store recovery codes

Remind the user to save their recovery codes in a secure location for account recovery.

Recovery Code Usage at Login

When a user has 2FA enabled but loses access to their authenticator app, they can use a recovery code in place of the totp_code field during login. Each recovery code can only be used once.

Login -- Login with 2FA code
Passkeys -- Alternative strong authentication with WebAuthn

Two-Factor Authentication