> For the complete documentation index, see [llms.txt](https://docs.securepass.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.securepass.me/documentation/api-reference/rest-api-support/mfa-api.md).

# MFA API

The MFA API registers a user's authentication method, issues the challenge and verifies the response.

It does not give each method its own endpoints. There is one lifecycle, and an `authType` field on the request decides which method it applies to.

| Stage                               | Endpoint                       |
| ----------------------------------- | ------------------------------ |
| Register a method for a user        | `POST /OTP/v1/registerOtp`     |
| Re-register, replacing what is held | `POST /OTP/v1/reRegisterOtp`   |
| Issue a challenge                   | `POST /OTP/v1/sendOtp`         |
| Verify the user's response          | `POST /OTP/v1/authenticateOtp` |
| Read the state of a challenge       | `POST /OTP/v1/fetchOtpDetails` |
| Remove a method from a user         | `POST /OTP/v1/deregisterAuth`  |

Adding a second factor to an application is therefore the same four calls whether the factor is an SMS code, an email code, a hardware token or an authenticator app. Only `authType` and the method-specific registration fields change — a mobile number for SMS, an email address for email OTP, a token serial for a hardware token.

## Password

Password is handled separately, because there is nothing to send and nothing to expire.

| Purpose                      | Endpoint                          |
| ---------------------------- | --------------------------------- |
| Set a password for a user    | `POST /OTP/v1/registerPassword`   |
| Replace an existing password | `POST /OTP/v1/reRegisterPassword` |
| Verify a password            | `POST /OTP/v1/validatePassword`   |

## Push notification

Push shares the registration and removal calls above, but its challenge is asynchronous — SECUREpass sends a prompt to the user's device and the result arrives separately, so there are extra endpoints to drive and poll it.

| Purpose                                 | Endpoint                               |
| --------------------------------------- | -------------------------------------- |
| Send the approval prompt to the device  | `POST /OTP/v1/triggerPushNotification` |
| Record the user's response from the app | `POST /OTP/v1/confirmPushNotification` |
| Poll for the outcome                    | `POST /OTP/v1/checkPushAuthStatus`     |
| Retrieve push authentication metrics    | `POST /OTP/v1/pushAuthMetrics`         |

The polling call is the one to get right. A caller that polls too aggressively wastes requests; one that gives up too early reports a failure for a user who was simply slow to reach their phone.

## QR code

QR code works the same way as push, and for the same reason: the user acts on a second device, so the result arrives separately from the request.

| Purpose                        | Endpoint                         |
| ------------------------------ | -------------------------------- |
| Present the code to be scanned | `POST /OTP/v1/triggerQrCode`     |
| Record the scan from the app   | `POST /OTP/v1/confirmQrCode`     |
| Poll for the outcome           | `POST /OTP/v1/checkQrAuthStatus` |

## Which methods are available

The methods an application can use are the ones enabled for your organisation under **Configuration → Authentication Modes**. *Reference → Authentication and MFA methods* lists what each method asks the user to present.