Complete 2FA Verification

After initiating a 2FA verification request, it's crucial to complete the process. The 'complete' API call serves as the final step in the 2FA verification process, confirming that the user has successfully authenticated using the chosen 2FA method.

The steps for completing 2FA verification vary based on the chosen authentication method:

For users verifying through the HyperID Authenticator App, the application should periodically make a 'complete' API call. The result of this call should be checked to determine whether the user has accepted or rejected the verification via the Authenticator App.
For TOTP verification, SMS, and email methods, the client application should wait until the user provides the verification code, which they receive from the respective source. Once the code is received from the user, the application should call the 'complete' API, passing this code to HyperID for verification.

To complete 2FA verification, services need to send a POST request to the HyperID API. This request requires the 'second-factor-auth-client' scope, which must be explicitly granted by the user during the authorization process.

Request

POST /2fa/verification/complete HTTP/1.1
Host: api.hypersecureid.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFjZDc0NGMzLWFlZDMtNGQxMC04ODZhLTcyYjU0MGY4NmU5YSJ9.eyJleHAiOjE2Nzk4MjM1NTEsImlhdCI6MTY3OTgxOTk1MSwiYXV0aF90aW1lIjoxNjc5ODE5OTUxLCJqdGkiOiIzM2ZlNzI2Ni1kOTY2LTRlNDgtYjU2My05ZWNhZTdjMWU3NTEiLCJpc3MiOiJodHRwczovL2xvZ2luLmh5cGVyc2VjdXJlaWQuY29tL2F1dGgvcmVhbG1zL0h5cGVySUQiLCJzdWIiOiI5MTZlMGUyZS00NmQ5LTRiODAtODg1Ni1kZDlmZWRiMWI3MjMiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjbGllbnQtc2VydmljZS1hcHAiLCJzY29wZSI6Im9wZW5pZCBlbWFpbCBrZXlzIGF1dGgiLCJzaWQiOiI5OTVjNzhhZC1lYmFjLTRhYWYtOTdiZC0xOTQ4ZWMxOWQzNzEiLCJ3YWxsZXRfYWRkcmVzcyI6IjB44oCmIiwid2FsbGV0X2NoYWluX2lkIjoiMSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJlbWFpbCI6InVzZXJAZ21haWwuY29tIn0.h9GusuxDPX8VOjPoZHD73XzktOkVtd1qEz6C8AuBybw
Content-Length: 73

{
    "auth_type": 1,
    "action_id": 7,
    "auth_code": "111111"
}

The auth_type should match the requested 2FA method.

The action_id is a unique identifier received in response from HyperID during the initiation of the 2FA verification process. It is used to match the corresponding 2FA verification.

The auth_code field represents the verification code:

For the HyperID Authenticator App, it should contain the auth_code_point value received during the initiation of 2FA verification;
For TOTP, SMS and email methods, it should hold the user-provided value received through the respective sources.

HyperID responds with a JSON object containing the information about 2FA confirmation result:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "result":        0,
    "action_id":     7,
    "next_check_dt": 1679315049,
}

The result field is an integer representation of complete result, with various possible values as listed in the table below:

Result Value	Meaning
3	The 2FA request is in a pending state when the user does not provide a response within the HyperID Authenticator App. In such cases, the client application should wait until the 'next_check_dt' timeframe has elapsed and make another attempt to complete the 2FA verification.
2	User has rejected the 2FA request within the HyperID Authenticator App
1	Invalid code provided. In such cases, the client application should wait until 'next_check_dt' timeframe has elapsed and make another attempt to complete the 2FA verification.
0	Success
-1	Failure because the service is temporarily unavailable
-2	Failure due to invalid request parameters
-3	Failure due to access denial
-4	Failure due to an expired token
-5	Failure due to an invalid token
-6	Failure due to unavailability of the specified 2FA type
-7	2FA check requested before the 'next_check_dt' timeframe

The action_id is a unique identifier received in 'complete' request. It is used to match the corresponding 2FA verification.

The next_check_dt shows when it becomes available to make another 2FA complete request for this user.

Below, you can find examples of 'Complete 2FA Verification' request implemented:

curl --location 'http://api.hypersecureid.com/2fa/verification/complete' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFjZDc0NGMzLWFlZDMtNGQxMC04ODZhLTcyYjU0MGY4NmU5YSJ9.eyJleHAiOjE2Nzk4MjM1NTEsImlhdCI6MTY3OTgxOTk1MSwiYXV0aF90aW1lIjoxNjc5ODE5OTUxLCJqdGkiOiIzM2ZlNzI2Ni1kOTY2LTRlNDgtYjU2My05ZWNhZTdjMWU3NTEiLCJpc3MiOiJodHRwczovL2xvZ2luLmh5cGVyc2VjdXJlaWQuY29tL2F1dGgvcmVhbG1zL0h5cGVySUQiLCJzdWIiOiI5MTZlMGUyZS00NmQ5LTRiODAtODg1Ni1kZDlmZWRiMWI3MjMiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjbGllbnQtc2VydmljZS1hcHAiLCJzY29wZSI6Im9wZW5pZCBlbWFpbCBrZXlzIGF1dGgiLCJzaWQiOiI5OTVjNzhhZC1lYmFjLTRhYWYtOTdiZC0xOTQ4ZWMxOWQzNzEiLCJ3YWxsZXRfYWRkcmVzcyI6IjB44oCmIiwid2FsbGV0X2NoYWluX2lkIjoiMSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJlbWFpbCI6InVzZXJAZ21haWwuY29tIn0.h9GusuxDPX8VOjPoZHD73XzktOkVtd1qEz6C8AuBybw' \
--data '{
    "auth_type": 2,
    "action_id": 3,
    "auth_code": "111111"
}'

var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFjZDc0NGMzLWFlZDMtNGQxMC04ODZhLTcyYjU0MGY4NmU5YSJ9.eyJleHAiOjE2Nzk4MjM1NTEsImlhdCI6MTY3OTgxOTk1MSwiYXV0aF90aW1lIjoxNjc5ODE5OTUxLCJqdGkiOiIzM2ZlNzI2Ni1kOTY2LTRlNDgtYjU2My05ZWNhZTdjMWU3NTEiLCJpc3MiOiJodHRwczovL2xvZ2luLmh5cGVyc2VjdXJlaWQuY29tL2F1dGgvcmVhbG1zL0h5cGVySUQiLCJzdWIiOiI5MTZlMGUyZS00NmQ5LTRiODAtODg1Ni1kZDlmZWRiMWI3MjMiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjbGllbnQtc2VydmljZS1hcHAiLCJzY29wZSI6Im9wZW5pZCBlbWFpbCBrZXlzIGF1dGgiLCJzaWQiOiI5OTVjNzhhZC1lYmFjLTRhYWYtOTdiZC0xOTQ4ZWMxOWQzNzEiLCJ3YWxsZXRfYWRkcmVzcyI6IjB44oCmIiwid2FsbGV0X2NoYWluX2lkIjoiMSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJlbWFpbCI6InVzZXJAZ21haWwuY29tIn0.h9GusuxDPX8VOjPoZHD73XzktOkVtd1qEz6C8AuBybw");

var raw = JSON.stringify({
  "auth_type": 2,
  "action_id": 3,
  "auth_code": "111111"
});

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("http://api.hypersecureid.com/2fa/verification/complete", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

const axios = require('axios');
let data = JSON.stringify({
  "auth_type": 2,
  "action_id": 3,
  "auth_code": "111111"
});

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'http://api.hypersecureid.com/2fa/verification/complete',
  headers: { 
    'Content-Type': 'application/json', 
    'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFjZDc0NGMzLWFlZDMtNGQxMC04ODZhLTcyYjU0MGY4NmU5YSJ9.eyJleHAiOjE2Nzk4MjM1NTEsImlhdCI6MTY3OTgxOTk1MSwiYXV0aF90aW1lIjoxNjc5ODE5OTUxLCJqdGkiOiIzM2ZlNzI2Ni1kOTY2LTRlNDgtYjU2My05ZWNhZTdjMWU3NTEiLCJpc3MiOiJodHRwczovL2xvZ2luLmh5cGVyc2VjdXJlaWQuY29tL2F1dGgvcmVhbG1zL0h5cGVySUQiLCJzdWIiOiI5MTZlMGUyZS00NmQ5LTRiODAtODg1Ni1kZDlmZWRiMWI3MjMiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjbGllbnQtc2VydmljZS1hcHAiLCJzY29wZSI6Im9wZW5pZCBlbWFpbCBrZXlzIGF1dGgiLCJzaWQiOiI5OTVjNzhhZC1lYmFjLTRhYWYtOTdiZC0xOTQ4ZWMxOWQzNzEiLCJ3YWxsZXRfYWRkcmVzcyI6IjB44oCmIiwid2FsbGV0X2NoYWluX2lkIjoiMSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJlbWFpbCI6InVzZXJAZ21haWwuY29tIn0.h9GusuxDPX8VOjPoZHD73XzktOkVtd1qEz6C8AuBybw'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

import http.client
import json

conn = http.client.HTTPSConnection("api.hypersecureid.com")
payload = json.dumps({
  "auth_type": 2,
  "action_id": 3,
  "auth_code": "111111"
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFjZDc0NGMzLWFlZDMtNGQxMC04ODZhLTcyYjU0MGY4NmU5YSJ9.eyJleHAiOjE2Nzk4MjM1NTEsImlhdCI6MTY3OTgxOTk1MSwiYXV0aF90aW1lIjoxNjc5ODE5OTUxLCJqdGkiOiIzM2ZlNzI2Ni1kOTY2LTRlNDgtYjU2My05ZWNhZTdjMWU3NTEiLCJpc3MiOiJodHRwczovL2xvZ2luLmh5cGVyc2VjdXJlaWQuY29tL2F1dGgvcmVhbG1zL0h5cGVySUQiLCJzdWIiOiI5MTZlMGUyZS00NmQ5LTRiODAtODg1Ni1kZDlmZWRiMWI3MjMiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjbGllbnQtc2VydmljZS1hcHAiLCJzY29wZSI6Im9wZW5pZCBlbWFpbCBrZXlzIGF1dGgiLCJzaWQiOiI5OTVjNzhhZC1lYmFjLTRhYWYtOTdiZC0xOTQ4ZWMxOWQzNzEiLCJ3YWxsZXRfYWRkcmVzcyI6IjB44oCmIiwid2FsbGV0X2NoYWluX2lkIjoiMSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJlbWFpbCI6InVzZXJAZ21haWwuY29tIn0.h9GusuxDPX8VOjPoZHD73XzktOkVtd1qEz6C8AuBybw'
}
conn.request("POST", "/2fa/verification/complete", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "http://api.hypersecureid.com/2fa/verification/complete");
request.Headers.Add("Authorization", "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImFjZDc0NGMzLWFlZDMtNGQxMC04ODZhLTcyYjU0MGY4NmU5YSJ9.eyJleHAiOjE2Nzk4MjM1NTEsImlhdCI6MTY3OTgxOTk1MSwiYXV0aF90aW1lIjoxNjc5ODE5OTUxLCJqdGkiOiIzM2ZlNzI2Ni1kOTY2LTRlNDgtYjU2My05ZWNhZTdjMWU3NTEiLCJpc3MiOiJodHRwczovL2xvZ2luLmh5cGVyc2VjdXJlaWQuY29tL2F1dGgvcmVhbG1zL0h5cGVySUQiLCJzdWIiOiI5MTZlMGUyZS00NmQ5LTRiODAtODg1Ni1kZDlmZWRiMWI3MjMiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjbGllbnQtc2VydmljZS1hcHAiLCJzY29wZSI6Im9wZW5pZCBlbWFpbCBrZXlzIGF1dGgiLCJzaWQiOiI5OTVjNzhhZC1lYmFjLTRhYWYtOTdiZC0xOTQ4ZWMxOWQzNzEiLCJ3YWxsZXRfYWRkcmVzcyI6IjB44oCmIiwid2FsbGV0X2NoYWluX2lkIjoiMSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJlbWFpbCI6InVzZXJAZ21haWwuY29tIn0.h9GusuxDPX8VOjPoZHD73XzktOkVtd1qEz6C8Au");
var content = new StringContent("{\r\n    \"auth_type\": 2,\r\n    \"action_id\": 3,\r\n    \"auth_code\": \"111111\"\r\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

PreviousStart 2FA Verification NextCustom MFA Requests

Last updated 7 months ago