Skip to main content

Admin MFA (v1)

Method & Path​

POST /api/v1/admin/mfa/totp/setup
POST /api/v1/admin/mfa/totp/confirm
POST /api/v1/admin/mfa/verify
GET /api/v1/admin/mfa/status

Description​

Multi-factor authentication (MFA) endpoints for admin accounts. Admins can enable TOTP (Time-based One-Time Password) authentication using authenticator apps like Google Authenticator, Authy, or Microsoft Authenticator.

Authentication​

Required: Admin authentication required for setup and status endpoints. No authentication required for verify endpoint (used during login flow).

Endpoints​

Setup TOTP​

POST /api/v1/admin/mfa/totp/setup

Generate a TOTP secret and QR code for admin account.

Headers​

Authorization: Bearer <admin_access_token>
Content-Type: application/json

Response 200 OK​

{
  "otpauthUri": "otpauth://totp/Placio:admin@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Placio",
  "qrCodeDataUrl": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

Response Fields​

  • otpauthUri (string): URI for adding to authenticator app
  • qrCodeDataUrl (string): Base64-encoded QR code image

Notes​

  • Secret is encrypted and stored securely (not returned in response)
  • QR code can be scanned with any TOTP authenticator app
  • Setup must be confirmed with /totp/confirm endpoint

Confirm TOTP Enrollment​

POST /api/v1/admin/mfa/totp/confirm

Confirm TOTP enrollment by verifying a code from the authenticator app.

Headers​

Authorization: Bearer <admin_access_token>
Content-Type: application/json

Request Body​

{
  "totpCode": "123456"
}

Request Fields​

  • totpCode (string, required): 6-digit TOTP code from authenticator app

Response 200 OK​

{
  "success": true,
  "message": "TOTP method enrolled successfully"
}

Common Errors​

  • 400 Bad Request: Invalid TOTP code format or code doesn't match
  • 401 Unauthorized: Admin authentication required

Verify MFA During Login​

POST /api/v1/admin/mfa/verify

Verify MFA code during login flow after initial password authentication.

Headers​

Content-Type: application/json

Request Body​

{
  "loginAttemptId": "507f1f77bcf86cd799439011",
  "totpCode": "123456"
}

Request Fields​

  • loginAttemptId (string, required): Challenge ID from login response
  • totpCode (string, required): 6-digit TOTP code from authenticator app

Response 200 OK​

{
  "admin": {
    "id": "507f1f77bcf86cd799439011",
    "email": "admin@example.com",
    "name": "Admin User",
    "role": "super_admin",
    "permissions": ["*"]
  },
  "meta": {
    "accessTokenExpiresIn": 3600,
    "refreshTokenExpiresIn": 604800
  }
}

Common Errors​

  • 400 Bad Request:
    • Challenge not found
    • Challenge already verified
    • Challenge expired
    • Too many verification attempts (max 5)
    • Invalid verification code
  • 404 Not Found: Challenge not found

Notes​

  • Challenge expires after a set time (typically 10 minutes)
  • Maximum 5 verification attempts per challenge
  • Successful verification issues access and refresh tokens

Get MFA Status​

GET /api/v1/admin/mfa/status

Get current MFA status for admin account.

Headers​

Authorization: Bearer <admin_access_token>

Response 200 OK​

{
  "hasTotp": true,
  "totpEnabled": true
}

Response Fields​

  • hasTotp (boolean): Whether TOTP method is configured
  • totpEnabled (boolean): Whether TOTP is currently enabled

Common Errors​

  • 401 Unauthorized: Admin authentication required

MFA Flow​

  1. Setup: Admin calls /totp/setup to get QR code
  2. Scan QR: Admin scans QR code with authenticator app
  3. Confirm: Admin calls /totp/confirm with code from app
  4. Login: During login, if MFA is enabled:
    • Admin provides email/password
    • System returns loginAttemptId and requires MFA
    • Admin calls /verify with TOTP code
    • System returns admin data and tokens

Security Notes​

  • TOTP secrets are encrypted at rest
  • QR codes are only shown once during setup
  • Challenge-based verification prevents replay attacks
  • Maximum 5 attempts per challenge
  • Challenges expire after set time period

Use Cases​

  1. Enhanced Security: Add extra layer of protection to admin accounts
  2. Compliance: Meet security requirements for sensitive operations
  3. Account Protection: Prevent unauthorized access even if password is compromised