Implementing MFA : Multi-Factor Authentication API guide

Find out how to integrate two-factor authentication (2FA) for your organization. Learn to create a TOTP connection for an Organization and generate a challenge for the user.

• Quickstart
• 15 min

A TOTP (Time-based One-Time Password) is a single-use, time-based password used as part of multi-factor authentication (MFA) to reinforce the security of access to web applications. After entering their usual credentials, users receive a unique code via a 2FA (Two-Factor Authentication) authenticator application such as Google Authenticator, Microsoft Authenticator, 2FAs, FreeOTP... or by SMS. This one-time password, or 'one-time passcode', must be entered into the application to finalize access to the service. This method, known as dual authentication, makes traditional authentication more robust and less vulnerable to attack.

To ensure maximum security, it is essential to implement security measures and ensure that the code can only be used for a short period of time. The use of one-time passwords via authentication applications has become essential to protect user accounts and data against cyberthreats.

Before starting

Create your free Cryptr account now, and you will have the two elements needed for this guide.

• API Key: You will receive a client_id and a client_secret. Read our guide to learn how to authenticate with these elements to use the Cryptr API.
• Organization: You will create your first organization, which could be your customer or yourself for a first test. Learn more about Organization API.

1. Enable MFA API login

To activate MFA Cryptr, you need to activate your MFA connection for the organization you have previously created in your dashboard.

To do this, access the page dedicated to the organization for which you wish to activate the MFA connection. You can select the organization via the User Directory side navigation bar on the left of your screen.

Once activated you will be able to use TOTP Challenges for the selected Organization.

2 Enroll your Users to TOTP

TOTP Enrollment

Before users can use an MFA like the TOTP, they must be enrolled. We will see how to do it:

Enroll your users

cURL

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/${user_id} \
    -d force_enroll='false'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();
urlencoded.append("force_enroll", "false");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer ***"

response = https.request(request)
puts response.read_body

info

The force_enroll parameter is used to re-enroll a user who has used all his recovery codes. A recovery code allows the user to re-register if he has lost his phone (and therefore his Authenticator application), for example, with his By default, a user cannot re-register more than 5 times without human verification.

This option can also be used to generate five new recovery_codes to replace the old ones.

Force user enrolment

cURL

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/${user_id} \
    -d force_enroll='true'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();
urlencoded.append("force_enroll", "true");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/x-www-form-urlencoded"
request["Authorization"] = "Bearer ***"
request.body = "force_enroll=true"

response = https.request(request)
puts response.read_body

This API call will give you a QR code that you need to display to your user, or you can use the OTP URI. If you wish to enroll your users for SMS, this is not necessary.

Verify User Enrollment

After enrolment, your users must confirm the activation of their 2FA method, either via a TOTP (Time-based One-Time Password) application, or by SMS .

• SMS method: Once registration has been completed, you need to send the user an SMS code, obtained during registration. The user must then enter this SMS code in your application.
• TOTP application method: The user will need to configure an authentication application (such as Google Authenticator) to generate temporary codes. Once configured, the user will need to enter the code generated by the TOTP application into your application.

In both cases, you can use our validation endpoint to verify the code entered by the user.

cURL

curl -X PUT ${cryptr_service_url}/api/v2/org/${org_domain}/totp-enrollment/validation/${user_id} \
    -d code='145632'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();
urlencoded.append("code", "145632");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/validation/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-enrollment/validation/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/x-www-form-urlencoded"
request["Authorization"] = "Bearer ***"
request.body = "force_enroll=145632"

response = https.request(request)
puts response.read_body

MFA Recovery code

After enrolling a user, you'll receive a payload containing five recovery codes. These will be supplied as a single String, each code separated by a line break, ready to be used in a textarea field to facilitate copy-pasting or hardcopy printing by the user.

These codes must be displayed so that the user can save them and use them if he loses access to his Authenticator application, phone or telephone number.

info

These recovery codes must be stored as carefully as a password (they must not be divulged or stored on the same device as the TOTP application...). Each time a recovery code is used, the user must re-register.

What's more, they are single-use, so a user can only use recovery codes 5 times. Once this number has been exceeded, you'll need to force a new enrolment so that the user can retrieve new ones (see the force_enroll parameter above). Finally, codes can only be used once in any 24-hour period.

3 Integrate the Multi-Factor authentication to your application

Receive one time code (For SMS method only)

The below call is useful only with SMS Method. For the TOTP Mobile App Method, the code is generated by the TOTP Application of the user, but in the case of the SMS Method, you have to generate the code to send to your Users.

Challenge a Totp

cURL

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/${user_id}

JavaScript

const myHeaders = new Headers();
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-challenge/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-challenge/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = "Bearer ***"

response = https.request(request)
puts response.read_body

This API call takes an user_id to create a TOTP challenge, which will create a TOTP code to send to your Users.

Verify OTP auth

Verify a Time based One Time Password auth

cURL

curl -X POST ${cryptr_service_url}/api/v2/org/${org_domain}/totp-challenge/validation/${user_id} \
  -d code='124578'

JavaScript

const myHeaders = new Headers();
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
myHeaders.append("Authorization", "Bearer ***");

const urlencoded = new URLSearchParams();
urlencoded.append("code", "145632");

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: urlencoded,
  redirect: "follow"
};

fetch("{cryptr_service_url}/api/v2/org/{org_domain}/totp-challenge/validation/{user_id}", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Ruby

require "uri"
require "net/http"

url = URI("{cryptr_service_url}/api/v2/org/{org_domain}/totp-challenge/validation/{user_id}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/x-www-form-urlencoded"
request["Authorization"] = "Bearer ***"
request.body = "force_enroll=145632"

response = https.request(request)
puts response.read_body

This API call function takes an user_id and a code to validate a TOTP challenge. If the challenge is validated then the authentication is successful.

info

Instead of using a TOTP code, users can use their recovery code. If a recovery code is used, you will have to enroll your user again. When a user uses his code, the recovery_code_used key will be set to true.

Response when a user has used their recovery code.

cURL

  {

    "__type__": "TotpChallenge",
    "challenged_at": "2023-08-22T15:00:55.816432",
    "code": "008029",
    "recovery_code_used": true, # This key will be set to true
    "request_id": "totp-challenge_2ULQbzNww3R4ANIZyroXwYsS8Wg",
    "sent_at": null,
    "success": true
}

If all five codes have been used, you can enroll your user one last time. After that, if the user loses access again, you'll need to force enrolment. This will give your user 5 new codes.

Full challenge process

1. After generating a TOTP challenge (SMS method only) you should get a code to send to your user.
2. You should then ask the user to enter the code received by SMS or through a TOTP App.
3. After that we check whether the challenge validation was successful ("success" property) or not. If so, the TOTP authentication is valid.
4. If the user has used a recovery code, you will need to enroll again immediately.

What’s next

You can also refer to our API references to perform these actions via the Rest API.