Docs

Trigger MFA using the API

You can trigger MFA challenges for enrolled authenticators by calling the /mfa/challenge endpoint.

OTP Challenges

To trigger an OTP challenge, make the appropriate POST call to mfa/challenge.


to configure this snippet with your account

curl --request POST \
  --url 'https://YOUR_DOMAIN/mfa/challenge' \
  --data '{ "client_id": "YOUR_CLIENT_ID", "challenge_type": "otp", "mfa_token": "Fe26.2**05..." }'

to configure this snippet with your account

var client = new RestClient("https://YOUR_DOMAIN/mfa/challenge");
var request = new RestRequest(Method.POST);
request.AddParameter("undefined", "{ \"client_id\": \"YOUR_CLIENT_ID\", \"challenge_type\": \"otp\", \"mfa_token\": \"Fe26.2**05...\" }", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

to configure this snippet with your account

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://YOUR_DOMAIN/mfa/challenge"

	payload := strings.NewReader("{ \"client_id\": \"YOUR_CLIENT_ID\", \"challenge_type\": \"otp\", \"mfa_token\": \"Fe26.2**05...\" }")

	req, _ := http.NewRequest("POST", url, payload)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

to configure this snippet with your account

HttpResponse<String> response = Unirest.post("https://YOUR_DOMAIN/mfa/challenge")
  .body("{ \"client_id\": \"YOUR_CLIENT_ID\", \"challenge_type\": \"otp\", \"mfa_token\": \"Fe26.2**05...\" }")
  .asString();

to configure this snippet with your account

var request = require("request");

var options = {
  method: 'POST',
  url: 'https://YOUR_DOMAIN/mfa/challenge',
  body: {client_id: 'YOUR_CLIENT_ID', challenge_type: 'otp', mfa_token: 'Fe26.2**05...'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

to configure this snippet with your account

#import <Foundation/Foundation.h>
NSDictionary *parameters = @{ @"client_id": @"YOUR_CLIENT_ID",
                              @"challenge_type": @"otp",
                              @"mfa_token": @"Fe26.2**05..." };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_DOMAIN/mfa/challenge"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"POST"];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];

to configure this snippet with your account

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://YOUR_DOMAIN/mfa/challenge",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{ \"client_id\": \"YOUR_CLIENT_ID\", \"challenge_type\": \"otp\", \"mfa_token\": \"Fe26.2**05...\" }",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

to configure this snippet with your account

import http.client

conn = http.client.HTTPSConnection("")

payload = "{ \"client_id\": \"YOUR_CLIENT_ID\", \"challenge_type\": \"otp\", \"mfa_token\": \"Fe26.2**05...\" }"

conn.request("POST", "/YOUR_DOMAIN/mfa/challenge", payload)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

to configure this snippet with your account

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://YOUR_DOMAIN/mfa/challenge")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request.body = "{ \"client_id\": \"YOUR_CLIENT_ID\", \"challenge_type\": \"otp\", \"mfa_token\": \"Fe26.2**05...\" }"

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

to configure this snippet with your account

import Foundation
let parameters = [
  "client_id": "YOUR_CLIENT_ID",
  "challenge_type": "otp",
  "mfa_token": "Fe26.2**05..."
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/mfa/challenge")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

If successful, you'll receive the following response:

{
  "challenge_type": "otp"
}

The user will collect a one-time password, which you will then collect from them. Proceed with the authentication process using /oauth/token as usual, adding the otp value that you collect as a parameter (format below) in the request.

{
	"name": "otp",
	"value": "000000"
}

OOB Challenges

To trigger an OOB challenge, make the appropriate POST call to mfa/challenge.

to configure this snippet with your account

{
	"method": "POST",
	"url": "https://YOUR_DOMAIN/mfa/challenge",
	"postData": {
		"mimeType": "application/json",
		"text": "{ \"client_id\": \"YOUR_CLIENT_ID\", \"challenge_type\": \"oob\", \"authenticator_id\": \"sms|dev_s...O\", \"mfa_token\": \"Fe26.2**05...\" }"
	}
}

If successful, you'll receive the following response, as well as an SMS message containing the required six-digit code:

{
  "challenge_type": "oob",
  "oob_code": "asdae35fdt5...oob_code_redacted",
  "binding_method": "prompt"
}

Proceed with the authentication process using /oauth/token as usual, sending the oob_code as a parameter (format below) in the request.

{
	"name": "oob_code",
	"value": "asdae35fdt5...oob_code_redacted"
}