Public API

MFA verification endpoints are publicly accessible (called during the login flow).

Multi-Factor Authentication

Add an extra layer of security with multi-factor authentication (MFA).

Overview

Olympus Cloud supports multiple MFA methods:

Method	Security Level	Use Case
TOTP	High	Authenticator apps (Google, Authy)
SMS	Medium	Text message codes
Email	Medium	Email verification codes
Push	High	Mobile app push notifications

---

Initiate TOTP Setup

Begin TOTP MFA enrollment by generating a secret and provisioning URI.

Request

POST /api/v1/auth/mfa/totp/initiate
Content-Type: application/json

{
  "user_id": "user-123",
  "label": "user@restaurant.com"
}

Response

Returns the TOTP secret, provisioning URI, and QR code data for scanning with an authenticator app.

---

Verify TOTP Setup

Complete TOTP setup by verifying a code from the authenticator app.

Request

POST /api/v1/auth/mfa/totp/verify
Content-Type: application/json

{
  "user_id": "user-123",
  "code": "123456"
}

Response

{
  "status": "ok"
}

---

Verify MFA During Login

When login returns mfa_required: true, verify MFA to complete authentication.

Request

POST /api/v1/auth/login/mfa
Content-Type: application/json

{
  "mfa_token": "mfa_challenge_token",
  "code": "123456",
  "method": "totp"
}

Response

Returns full login response with access and refresh tokens.

---

MFA Methods

TOTP (Recommended)

Time-based One-Time Password using authenticator apps.

Backup Codes Critical

After enabling MFA, immediately save your backup codes in a secure location. These codes are the only way to regain access if you lose your authenticator device. Each code can only be used once.

Setup Flow:

1. Call POST /auth/mfa/totp/initiate with user ID and label
2. Scan QR code with authenticator app
3. Verify with code from app via POST /auth/mfa/totp/verify
4. Generate backup codes via POST /auth/mfa/backup-codes/generate

Compatible Apps:

• Google Authenticator
• Authy
• 1Password
• Microsoft Authenticator

SMS

Text message verification codes.

Setup:

{
  "method": "sms",
  "phone_number": "+1234567890"
}

Limitations:

• Requires verified phone number
• Subject to carrier delays
• Not recommended for high-security accounts

Email

Email verification codes.

Setup:

{
  "method": "email"
}

Uses the account's primary email address.

---

Backup Codes

One-time use codes for account recovery.

Generate Backup Codes

POST /api/v1/auth/mfa/backup-codes/generate
Content-Type: application/json

{
  "user_id": "user-123"
}

Response:

{
  "codes": [
    "abc123def456",
    "ghi789jkl012",
    "mno345pqr678",
    "stu901vwx234",
    "yza567bcd890"
  ]
}

Use Backup Code

During login MFA challenge, submit a backup code instead of a TOTP code:

POST /api/v1/auth/login/mfa
Content-Type: application/json

{
  "mfa_token": "mfa_challenge_token",
  "code": "abc123def456",
  "method": "backup_code"
}

---

Disable MFA

Request

POST /api/v1/auth/mfa/disable
Content-Type: application/json

{
  "user_id": "user-123",
  "factor_id": "factor-uuid"
}

Response

{
  "status": "disabled"
}

---

List MFA Devices

List all MFA devices/factors enrolled for a user.

Request

POST /api/v1/auth/mfa/devices
Content-Type: application/json

{
  "user_id": "user-123"
}

Response

{
  "devices": [
    {
      "id": "factor-uuid",
      "type": "totp",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

---

Tenant MFA Policy

Enforce MFA at the tenant level.

Policy Options

Setting	Description
mfa_required	Require MFA for all users
mfa_required_roles	Require MFA for specific roles
allowed_methods	Restrict to certain MFA methods
grace_period_days	Days to enable MFA after policy

Example Policy

{
  "mfa_required": true,
  "mfa_required_roles": ["manager", "owner", "admin"],
  "allowed_methods": ["totp", "push"],
  "grace_period_days": 7
}

---

Error Responses

Invalid Code (401)

{
  "error": {
    "code": "INVALID_MFA_CODE",
    "message": "The verification code is invalid or expired",
    "attempts_remaining": 2
  }
}

MFA Locked (423)

{
  "error": {
    "code": "MFA_LOCKED",
    "message": "Too many failed attempts. Try again later.",
    "unlock_at": "2026-01-18T10:45:00Z"
  }
}

---

Security Best Practices

1. Use TOTP over SMS - More secure against SIM swap attacks
2. Store backup codes safely - Treat like passwords
3. Enforce MFA for admins - Require for privileged roles
4. Monitor MFA events - Alert on unusual activity
5. Regular audits - Review MFA enrollment status

---

Related Documentation

• Login API - Authentication
• Sessions - Session management
• Security Best Practices - Security guide