API Documentation

Get Rapid 2FA working in few minutes.

Integrating Rapid 2FA is fairly simple, takes 3 API calls and no UI changes. Besides, the integration is simple and can be done without any major changes in the code of your website. Let's get going!

Overview

The integration has some three crucial parts explained below.

1. Creating 2FA sessions. You will have to make an API call to our servers to generate a 2FA session for the user account. Afterwards you need to redirect the user to the authentication URL passed by our system.

2. Verifying the authentication. After a user has authentication at our hosted page, they are redirected back to your callback URL with a secure hash. You have to make another HTTP request to us with the hash passed by the user (in a GET request). This enables to confirm the integrity of the hash passed by the user. Our server will validate the hash and let you know if it's valid or not.

3. Edit profile page (User 2FA Settings). Now, if the user's logged-in properly, you have to place a link at your Account Settings page to let them manage their 2FA settings. You've to send an API call to our servers and we will generate a secure link for them to edit their 2FA settings. You simply have to redirect them to the link (after they click to change their 2FA settings).


Before we get going to the code part, here are some things to consider.

1. Generating API Key. You need to generate an API Key and API Secret to integrate your site with Rapid 2FA. You can generate them easily by signing up to a plan.

2. Server libraries. We've multiple server libraries. We're using them in this guide. If you want to see the raw code, you might consider reading the code of our libaries available at GitHub. You can find the links at the right side of the page.

3. API Endpoint. Our API Endpoint is located at the following URL: https://rapid2fa.com/api/


Generating 2FA settings page

The setting page enables your users to enable/disable 2FA, create backup codes, manage their devices. The procedure is simple, you need to make a call for the user and then we'll reply back with a link. You need to redirect the user (or open in a new tab with JavaScript) to the link so that they can manage their 2FA page.

With API Key and API Secret, let's generate a Settings page for one of your users.

<?php

define("API_KEY","YOUR_RAPID_2FA_API_KEY_HERE"); // Get from Rapid2FA.com
define("API_SECRET","YOUR_RAPID_2FA_API_SECRET_HERE"); // Get from Rapid2FA.com
$user_id = 100; // Load from database/session.
$method = 'javascript'; // Change to redirect to relocate the user to the page.

try {

$client = new Rapid2FA(API_KEY,API_SECRET);
$settings = $client->generateSettingsPage($user_id);
$link = $settings['hosted_page'];

if($method == 'javascript') {

echo '<script>

var url = "' . $link . '";
var a = document.createElement("a");
a.target = "_blank";
a.href = url;
a.click();

</script>';

} else {

header("Location: " . $link);

}

} catch(Exception $e) {

//Can be anything, but not ER-05200.
$error = $e->getMessage();

}

?>

const Rapid2FA = require('rapid2fa');

var user = user_id; // Put the user ID here.

var rapid2fa = new Rapid2FA({
api_key: 'YOUR_API_KEY_HERE',
api_secret: 'YOUR_API_SECRET_HERE'
});

rapid2fa.generateSettingsPage(user, function(response) {

console.log(response);

});

from urllib.parse import urlencode
from urllib.request import Request, urlopen

api_key = 'YOUR_API_KEY_HERE'
api_secret = 'YOUR_API_SECRET_HERE'
user = user_id # Put user ID here.

url = 'https://rapid2fa.com/api/' # API Endpoint
post_fields = {'api_key': api_key, 'api_secret': api_secret, 'method': 'edit_profile_2fa', 'user': user} # POST data here

request = Request(url, urlencode(post_fields).encode())
json = urlopen(request).read().decode()
print(json)

require 'net/http'

api_endpoint = 'https://rapid2fa.com/api/'
api_key = 'YOUR_API_KEY_HERE'
api_secret = 'YOUR_API_SECRET_HERE'
user = user_id; # Put user ID here.

postData = Net::HTTP.post_form(URI.parse(api_endpoint), {'api_key' => api_key, 'api_secret' => api_secret, 'method' => 'edit_profile_2fa', 'user' => user})
puts postData.body

curl -d "api_key=API_KEY&api_secret=API_SECRET&method=edit_profile_2fa&user=USER_ID" https://rapid2fa.com/api/


In the examples above, we initialize the SDK with our API Key and API Secret. Then, we pass the user ID to a function to generate the settings page for your user. User ID is any value that uniquely identifies a user. It must not exceed 128 characters.

Now, you can use the settings page. You can either redirect the user to the 2FA settings page or open the 2FA page in a new tab using JavaScript.

Making a user 2FA session

To use our 2FA, you need to generate a 2FA session for the user by making an API call to our servers and then redirecting the user to the hosted page URL returned in the response.

<?php

define("API_KEY","YOUR_RAPID_2FA_API_KEY_HERE"); // Get from Rapid2FA.com
define("API_SECRET","YOUR_RAPID_2FA_API_SECRET_HERE"); // Get from Rapid2FA.com
$user_id = 100; // Load from database/session.

try {

$client = new Rapid2FA(API_KEY,API_SECRET);
$session = $client->generate2FASession($user_id);
$link = $session['hosted_page'];

if($session['2fa_enabled'] == false) {

activateUserSession(); //Activate the user session now (because 2FA is not enabled).

} else {

header("Location: " . $link);

}

} catch(Exception $e) {

//Can be anything, but not ER-05200.
$error = $e->getMessage();

}

?>

const Rapid2FA = require('rapid2fa');

var user = user_id; // Put the user ID here.

var rapid2fa = new Rapid2FA({
api_key: 'YOUR_API_KEY_HERE',
api_secret: 'YOUR_API_SECRET_HERE'
});

rapid2fa.generate2FASession(user, function(response) {

console.log(response);

});

from urllib.parse import urlencode
from urllib.request import Request, urlopen

api_key = 'YOUR_API_KEY_HERE'
api_secret = 'YOUR_API_SECRET_HERE'
user = user_id # Put user ID here.

url = 'https://rapid2fa.com/api/' # API Endpoint
post_fields = {'api_key': api_key, 'api_secret': api_secret, 'method': 'create_2fa_session', 'user': user} # POST data here

request = Request(url, urlencode(post_fields).encode())
json = urlopen(request).read().decode()
print(json)

require 'net/http'

api_endpoint = 'https://rapid2fa.com/api/'
api_key = 'YOUR_API_KEY_HERE'
api_secret = 'YOUR_API_SECRET_HERE'
user = user_id # Put user ID here.

postData = Net::HTTP.post_form(URI.parse(api_endpoint), {'api_key' => api_key, 'api_secret' => api_secret, 'method' => 'create_2fa_session', 'user' => user})
puts postData.body

curl -d "api_key=API_KEY&api_secret=API_SECRET&method=create_2fa_session&user=USER_ID" https://rapid2fa.com/api/


In the examples above, we use our API Key and API Secret along with the uniquely identifying User ID to generate a sesssion (and a hosted page) for the user. You have to then redirect the user to our hosted page for 2FA authentication.

N.B.: We'll also let you know if the user has 2FA enabled or not. In that case, you can decide NOT to redirect the user to hosted page, but instead log them in directly. It wouldn't make any sense to redirect the user to hosted page if the 2FA is not enabled. However, if you still redirect the user to the hosted page, the process would still go as expected. We'll instantly redirect the user back to your callback URL with an authentication hash (but, in real sense, no authentication would have been done).

Verifying user sessions

Once a user has authenticated successfully at out hosted page, they are redirected back to your callback page (set in API settings) with a GET variable holding a hash. This hash is used to validate the integrity of the session. You've to pass this hash to us and we'll let you know if you should log the user in or not.

<?php

define("API_KEY","YOUR_RAPID_2FA_API_KEY_HERE"); // Get from Rapid2FA.com
define("API_SECRET","YOUR_RAPID_2FA_API_SECRET_HERE"); // Get from Rapid2FA.com
$hash = $_GET['hash']; // Load from GET (callback URL: http://website.com/rapid2fa_callback.php?hash=*).
$user_id = 100; // From your database.

try {

$client = new Rapid2FA(API_KEY,API_SECRET);
$validity = $client->handleVerification($user_id,$hash);

if($validity['status'] == true) {

activateUserSession(); //Activate the user session now.

} else {

header("Location: login"); // It's likely an attempt to game the system. Redirect the user back to site, logout them out, block them?

}

} catch(Exception $e) {

//Can be anything, but not ER-05200.
$error = $e->getMessage();

}

?>

const Rapid2FA = require('rapid2fa');

var hash = hash; // Put the hash returned here in the GET request.
var user = user_id; // Put the user ID here.

var rapid2fa = new Rapid2FA({
api_key: 'YOUR_API_KEY_HERE',
api_secret: 'YOUR_API_SECRET_HERE'
});

rapid2fa.handleVerification(user, hash, function(response) {

console.log(response);

});

from urllib.parse import urlencode
from urllib.request import Request, urlopen

api_key = 'YOUR_API_KEY_HERE';
api_secret = 'YOUR_API_SECRET_HERE';
hash = request.GET['hash']; # Retrieve the hash from the GET request
user = user_id; # Put user ID here.

url = 'https://rapid2fa.com/api/' # API Endpoint
post_fields = {'api_key': api_key, 'api_secret': api_secret, 'method': 'verify_authentication', 'user': user, 'hash': hash} # POST data here

request = Request(url, urlencode(post_fields).encode())
json = urlopen(request).read().decode()
print(json)

require 'net/http'

api_endpoint = 'https://rapid2fa.com/api/';
api_key = 'YOUR_API_KEY_HERE';
api_secret = 'YOUR_API_SECRET_HERE';
hash = hash; # Put verification here after the GET request.
user = user_id; # Put user ID here.

postData = Net::HTTP.post_form(URI.parse(api_endpoint), {'api_key' => api_key, 'api_secret' => api_secret, 'method' => 'create_2fa_session', 'user' => user, hash' => hash})
puts postData.body

curl -d "api_key=API_KEY&api_secret=API_SECRET&method=verify_authentication&user=USER_ID&hash=HASH" https://rapid2fa.com/api/


In the examples above, we simply send a request to the API handler with the hash and it replies back with the validity of the hash - if it's valid or not.

Responses and error codes

While you use our API, you might come across with multiple response codes. Everytime, our API responds with a response code and response text in JSON, however response text may not be suitable for managing the errors, they are merely added as a description of the status.

Error codes can be efficiently used for managing and logging the errors. We've made a list of status codes that you're likely to come across while using our API.

  • ER-05401 - The API key/secret is not valid or your application has been disabled.
  • ER-05402 - Your IP address has not been whitelisted to access the resources.
  • ER-05403 - You have accessed an invalid method.
  • ER-05404 - The user ID parameter is blank.
  • ER-05405 - The user ID parameter length exceeds 128 characters.
  • ER-05200 - Successful. Check other parameters to obtain the information.

These error codes are present in status_code key which you get after parsing it. The description is also present in message key.