TOTP Setup
Set up time-based one-time password (TOTP) authentication.
Start Setup
/auth/admin/mfa/totp/setupInitialize TOTP setup. Returns a secret and QR code URL for authenticator apps.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer {access_token} |
Response- TOTP setup information
{
"secret": "JBSWY3DPEHPK3PXP",
"otpauth_url": "otpauth://totp/WalletCore:admin@example.com?secret=JBSWY3DPEHPK3PXP&issuer=WalletCore",
"recovery_codes": [
"ABC123DEF456",
"GHI789JKL012",
"MNO345PQR678",
"STU901VWX234",
"YZA567BCD890"
]
}Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | mfa_already_enabled | MFA is already enabled for this account |
Confirm Setup
/auth/admin/mfa/totp/confirmConfirm TOTP enrollment by providing a valid code from your authenticator app.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer {access_token} |
Content-Type | string | Yes | application/json |
Request Body- TOTP code to confirm
{
"code": "123456"
}Response- No content on success (HTTP 204)
Error Responses
| Status | Code | Description |
|---|---|---|
| 401 | mfa_confirm_failed | Invalid TOTP code |
MFA Verification
Verify MFA during login flow.
Verify TOTP Code
/auth/admin/mfa/verifyComplete login by verifying TOTP code. This endpoint is used after initial login when MFA is required.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Content-Type | string | Yes | application/json |
Request Body- Pending token and TOTP code
{
"pending_token": "pending_token_from_login",
"code": "123456"
}Response- Authentication tokens
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
"token_type": "Bearer",
"expires_in": 3600
}Error Responses
| Status | Code | Description |
|---|---|---|
| 401 | mfa_verify_failed | Invalid or expired TOTP code |
| 429 | mfa_locked | Too many failed attempts (10/min, 120/day) |
Recovery Codes
Manage MFA recovery codes for account recovery.
Use Recovery Code
/auth/admin/mfa/recoveryComplete login using a recovery code when TOTP device is unavailable.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Content-Type | string | Yes | application/json |
Request Body- Pending token and recovery code
{
"pending_token": "pending_token_from_login",
"recovery_code": "ABC123DEF456"
}Response- Authentication tokens
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
"token_type": "Bearer",
"expires_in": 3600
}Error Responses
| Status | Code | Description |
|---|---|---|
| 401 | recovery_verify_failed | Invalid or already used recovery code |
| 429 | mfa_locked | Too many failed attempts (5/min, 60/day) |
Get Recovery Code Count
/auth/admin/mfa/recovery/countGet the number of remaining recovery codes.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer {access_token} |
Response- Recovery code count
{
"remaining": 3
}Regenerate Recovery Codes
/auth/admin/mfa/recovery/regenGenerate new recovery codes. This invalidates all existing recovery codes.
Headers
| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | string | Yes | Bearer {access_token} |
Content-Type | string | Yes | application/json |
Request Body- Optional count of codes to generate
{
"count": 10
}Response- New recovery codes
{
"recovery_codes": [
"NEW123ABC456",
"DEF789GHI012",
"JKL345MNO678",
"PQR901STU234",
"VWX567YZA890"
]
}MFA Login Flow
Understanding the complete MFA authentication flow.
Authentication Steps
| Step | Action | Response |
|---|---|---|
| 1 | POST /auth/admin/login with credentials | Returns pending_token if MFA enabled |
| 2a | POST /auth/admin/mfa/verify with TOTP code | Returns access_token and refresh_token |
| 2b | POST /auth/admin/mfa/recovery with recovery code | Alternative: Returns tokens |
| 2c | POST /auth/admin/webauthn/login with passkey | Alternative: Returns tokens |