Docs

Associate a One-Time Password Authenticator

In this tutorial, you'll learn how to configure your application so users can self-associate one-time password (OTP) authenticators.

Before you start

Before you can use the MFA APIs, you'll need to enable the MFA grant type for your application. You can enable the MFA grant by going to Applications > Your Application > Advanced Settings > Grant Types and selecting MFA.

1. Get the MFA Token

When a user begins the authorization process without an active authenticator associated with their account, they will trigger the an mfa_required error when calling the /oauth/token endpoint. The request might look something like this:




However, if MFA is required for this user, the mfa_required error will look like this:

In the next step, use the MFA token (mfa_token) received in this response instead of the standard Access Token to request association of a new authenticator.

2. Request association of the authenticator

Next, make a POST request to the /mfa/associate endpoint to request association of the user's authenticator. The Access Token required by this endpoint is the MFA token received in the previous step.

To associate an authenticator where the challenge type is an OTP code the user provides, make the following POST request to the /mfa/associate endpoint. This will both trigger an MFA challenge for the user and associate the new authenticator.

Be sure to replace the placeholder values in the payload body shown below as appropriate.




If successful, you'll receive a response like this:

In the next step, you'll need the one-time password (otp), which can be obtained by using the barcode_uri to generate a QR code that can be scanned by the OTP generator of your choice (such as Guardian). Once the user scans that QR code, they will be able to obtain the OTP code.

You might also consider displaying the secret in plain text so that your users can copy and paste it directly into the OTP generator (this is especially helpful for users on desktop applications).

Recovery Codes

If this is the first time the user is associating an authenticator, you'll notice the response includes recovery_codes. Recovery codes are used to access the user's account in the event that they lose access to the account or device used for their second factor authentication. These are one-time usable codes, and new ones are generated as necessary.

3. Confirm the authenticator association

Once the authenticator is associated, it must be used at least once to confirm the association.

To confirm the association of an authenticator using OTP, make a POST request to the oauth/token endpoint, including the otp value that is collected from the user after they have set up their OTP generator.

Be sure to replace the placeholder values in the payload body shown below as appropriate.




If the call was successful, you'll receive a response in the below format, containing the Access Token:

At this point, the authenticator is fully associated and ready to be used, and you have an Access Token for the user.

You can check at any point to verify whether an authenticator has been confirmed by calling the mfa/authenticators endpoint. If the authenticator is confirmed, the value returned for active is true.