Multi-Factor Authentication (MFA)

On this page, we’ll dive into the different MFA endpoints you can use to manage MFA programmatically.

Multi Factor Authentication (MFA) is a security feature that requires a user to provide more than one form of authentication when logging in. You can use the DevRIFT API to implement MFA easily for your users.

You can use verify an end-user via several different methods, including:

• Email
• SMS / WhatsApp
• Phone Call
• Authenticator App
• Security Keys (HSM)
• And our Dual MFA System (Enterprise only)

MFA Code Verification

To verify a user's MFA code, you can use the /v1/mfa/verify endpoint. This endpoint will verify the code and return a 200 response if the code is valid. If the code is invalid, it will return a 401 response.

# Verify an MFA Code sent via Email
curl -X POST https://api.devrift.co/v1/mfa/verify \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_EMAIL, Type=EMAIL, Code=YOUR_USERS_MFA_CODE"

# Verify an MFA Code sent via SMS / WhatsApp / Phone Call
curl -X POST https://api.devrift.co/v1/mfa/verify \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_PHONE_NUMBER, Type=PHONE, Code=YOUR_USERS_MFA_CODE"

# Verify an MFA Code sent via the Authenticator App
curl -X POST https://api.devrift.co/v1/mfa/verify \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_CONTACT, Type=APP, Code=YOUR_USERS_MFA_CODE"

# Verify an MFA Code sent via the Dual MFA System
curl -X POST https://api.devrift.co/v1/mfa/verify \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_EMAIL:YOUR_USERS_PHONE_NUMBER, Type=DUAL, Code=YOUR_USERS_MFA_CODE"

MFA Methods

MFA via Email

To enable this endpoint, you must first configure MFA in your Application's settings. Found here. Then enable MFA via Email.

To send a MFA code to a user's email, you can do the following:

curl -X POST https://api.devrift.co/v1/mfa \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_EMAIL, Type=EMAIL"

MFA via SMS

To enable this endpoint, you must first configure MFA in your Application's settings. Found here. Then enable MFA via SMS.

To send a MFA code to a user's phone number, you can do the following:

curl -X POST https://api.devrift.co/v1/mfa \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_PHONE_NUMBER, Type=SMS"

Dual MFA System

The Dual MFA System is a system that allows you to use multiple MFA methods at the same time. This is useful if you want to use a more secure MFA method, but also want to allow users to use a less secure method if they don't have access to the more secure method.

To enable this endpoint, you must first configure MFA in your Application's settings. Found here. Then enable the Dual MFA System.

Then, to send an MFA Code to a user's email and phone number, you can do the following:

curl -X POST https://api.devrift.co/v1/mfa \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_EMAIL:YOUR_USERS_PHONE_NUMBER, Type=DUAL"

Authenticator App

Before you can use the Authenticator App, you must first enable it in your Application's settings. Found here. Then enable MFA via an Authenticator App.

In order for a user to use an Authenticator App to verify themselves, they must first set it up. You can do this by sending our API a request to generate a QR Code for the user to scan. The API will generate a QR code and return it in the response as a base64 encoded string.

You'll need to display this QR code to the user and have them scan it with their Authenticator App. Once they've scanned the QR code, they'll need to enter the code that the Authenticator App generates. You can then verify the code using the /v1/mfa/verify endpoint.

You can use our RIFT Elements Frontend Library to display the QR code to the user.

Generating Backup Codes for an End-User

You can generate backup codes for an end-user by sending a request to the /v1/mfa/backup endpoint. This endpoint will send a list of backup codes to the end-user's email address or phone number. You can also change other details like the number and length of the backup codes in the DevRIFT Dashboard.

# Via Email
curl -X POST https://api.devrift.co/v1/mfa/backup \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_EMAIL, Type=EMAIL"

# Or via SMS
curl -X POST https://api.devrift.co/v1/mfa/backup \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_PHONE_NUMBER, Type=SMS"

# Dual System (Enterprise Only)
curl -X POST https://api.devrift.co/v1/mfa \
    -H "Authorization: Bearer {sk_test_foobar...}" \
    -d "User=YOUR_USERS_EMAIL:YOUR_USERS_PHONE_NUMBER, Type=DUAL"