Auth API Reference
The Futurae Auth API can be used in order to add authentication and transaction signing to your website or application (also referred to as Service), or integrate any of the offered authentication factors into your existing authentication platform.
This document describes in detail how to format the HTTP Requests for calling the API endpoints, as well as the format of each individual HTTP request and response. In order to get an overview of how to use the API, refer to the Auth API guide.
Current Auth API Version: 1.36.0
Version History (change log)
Getting Started
The Futurae Auth API operates on Futurae Services. A Futurae Service represents one of your end-user applications (or a set of applications, if they are all using the same user Identity Database), which is to be protected with Futurae authentication. The end users of your application must be enrolled in the corresponding Futurae Service, thereby creating a mapping of your end users into Futurae, which we call Futurae users.
Each Service belongs to an Organization in Futurae Admin. Refer to this article to learn more about managing Services and Organizations in Futurae Admin.
In order to be able to use the Auth API you will need to get your Service credentials: Service ID, Auth API key and Service hostname (which is the host part of the Service Base URL). Additionally, you can use the Callback Signature key to verify callback signatures. You can get these credentials from Futurae Admin.
The communication with the Futurae server takes place only over TCP port 443, using HTTPS. Please use the provided Service hostname to connect to our servers, and not hardcoded IP addresses as these are subject to change over time.
The Service hostname will typically have the form: xxxxxx.futurae.com
, for example api.futurae.com
. In this case you would connect to https://api.futurae.com
and invoking the endpoints specified in this document.
Postman Sample Collection
To help you with integration, we provide a postman collection with a few sample Auth API endpoints.
Once you import the collection into Postman, you will need to edit it and adjust the following variables:
Variable | Value |
---|---|
hostname | Your Service Hostname (example: api.futurae.com ) |
service_id | Your Service ID |
auth_api_key | Your Auth API key |
Request Format
For calling the API endpoints, the request URI consists of the Service hostname, the Auth API version prefix and the endpoint together with any potential parameters (each endpoint showcases an example URI on how to call it).
Headers
Each request must contain an FT-Date
header, containing the current time formatted as RFC 2822 and an Authorization
header (see Request Authentication on how to construct the Authorization
header in order to authenticate each request).
Parameters
For GET and DELETE requests any parameters must be URL-encoded and sent in the URL query string.
For POST and PUT requests, the header Content-Type: application/json
must be supplied and the parameters must be sent in the request body as JSON-formatted key/value pairs. For example:
{"user_id":"70d63df1-d20d-4530-ac92-aa6f9f6f329e","valid_secs":86400}
Input Field Restrictions
The following input fields are restricted in terms of maximum length and characters that they may contain.
username
(maximum length: 100 characters): Can be a string with no spaces and with case-sensitive letters ([a-zA-Z]), numbers, or the characters. _ - = @ # $ +
display_name
(maximum length: 100 characters): Can be a string with spaces and with case-sensitive Unicode letters (Unicode L character class), Unicode punctuation (Unicode P character class), numbers, or the characters= @ # $ +
Request Authentication
In order to successfully call the API endpoints you need to authenticate your requests, by signing them using your Auth API key as the signing key. The supplied Authorization
header must carry the required signature using the HTTP Basic Authentication format as follows:
Authorization header format:
Authorization: Basic base64( Service_ID:hex( hmac( Auth_API_Key, request_content ) ) )
- The HTTP username will be your Service ID.
- The HTTP password will be a hex-formatted HMAC-SHA256 signature, computed over the request content in the way described below, using the Auth API key as the HMAC key.
- The HTTP username and password are concatenated using a colon, and the concatenated string is Base64 encoded.
The signature must be computed over an ASCII string, consisting of the following request components, which must be concatenated with newline characters ('\n'):
To compute the HMAC signature, use this code:
#############################################
# Python 3
#############################################
import base64, email.utils, hmac, json, hashlib
def signpython(method, host, path, params, sid, skey):
"""
Return HTTP Basic Authentication ("Authorization" and "FT-Date") headers.
method: Request method string
host: Request host string (without port and without the "https://" prefix)
path: Request path (includes query params)
params: Dict of request body parameters
sid: Service ID
skey: Auth API key
"""
params = json.dumps(params) if bool(params) else ''
now = email.utils.formatdate()
values = [now, method.upper(), host.lower(), path, params]
data = '\n'.join(values) + '\n'
sig = hmac.new(skey.encode(), data.encode(), hashlib.sha256)
auth = '%s:%s' % (sid, sig.hexdigest())
return {'FT-Date': now, 'Authorization': 'Basic %s' % base64.b64encode(auth.encode()).decode()}
require 'base64'
require 'openssl'
require 'time'
# Return HTTP Basic Authentication ("Authorization" and "FT-Date") headers.
#
# * +method+ - Request method string
# * +host+ - Request host string (without port and without the "https://" prefix)
# * +path+ - Request path (includes query params)
# * +params+ - Dict of request body params
# * +sid+ - Service ID
# * +skey+ - Auth API key
def sign(method, host, path, params, sid, skey)
params = params.empty? ? '' : params.to_json
now = Time.now.rfc2822
values = [now, method.upcase, host.downcase, path, params]
data = values.join("\n") << "\n"
digest = OpenSSL::Digest.new('sha256')
sig = OpenSSL::HMAC.hexdigest(digest, skey, data)
auth = Base64.strict_encode64("#{sid}:#{sig}")
{ 'FT-Date' => now, 'Authorization' => "Basic #{auth}" }
end
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"fmt"
"strings"
"time"
)
// Request represents the struct to be signed. Initialize it with the HTTP
// method, host (without port and without the "https://" prefix),
// path (including the query parameters) and body params stringified.
type Request struct {
Method string
Host string
Path string
Params string
}
// Sign accepts the Service ID and Auth API key and returns HTTP
// Basic Authentication ("Authorization" and "FT-Date") headers.
func (req *Request) Sign(serviceID, serviceKey string) map[string]string {
params := req.Params + "\n"
date := getDateRFC2822(time.Now())
values := []string{
date,
strings.ToUpper(req.Method),
strings.ToLower(req.Host),
req.Path,
params,
}
data := strings.Join(values, "\n")
sig := hmac.New(sha256.New, []byte(serviceKey))
sig.Write([]byte(data))
auth := fmt.Sprintf("%s:%s", serviceID, hex.EncodeToString(sig.Sum(nil)))
return map[string]string{
"FT-Date": date,
"Authorization": "Basic " + base64.StdEncoding.EncodeToString([]byte(auth)),
}
}
func getDateRFC2822(t time.Time) string {
RFC2822 := "Mon, 02 Jan 2006 15:04:05 -0700"
return t.UTC().Format(RFC2822)
}
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;
import java.util.Base64;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;
public class Sign {
private static final String RFC_2822_PATTERN = "EEE, dd MMM yyyy HH:mm:ss Z";
private static final DateTimeFormatter rfc2822Formatter = DateTimeFormatter.ofPattern(RFC_2822_PATTERN, Locale.US);
/**
* Return HTTP Basic Authentication ("Authorization" and "FT-Date") headers.
*
* @param method request HTTP method
* @param host request host string (without port and without the "https://" prefix)
* @param path request path (including query params)
* @param params request body parameters stringified
* @param sid Service ID
* @param skey Auth API key
*/
public static Map<String, String> requestHeaders(String method, String host, String path, String params, String sid, String skey) throws InvalidKeyException, NoSuchAlgorithmException {
params = (params == null) ? "" : params;
String date = OffsetDateTime.now().format(rfc2822Formatter);
String[] values = new String[]{date, method, host, path, params};
StringBuilder data = new StringBuilder();
for (String val : values) {
data.append(val);
data.append("\n");
}
String sig = bytesToHex(digest(data.toString(), skey));
String auth = sid + ":" + sig;
Map<String, String> headers = new HashMap<>();
headers.put("FT-Date", date);
headers.put("Authorization", "Basic " + Base64.getEncoder().encodeToString(auth.getBytes(StandardCharsets.UTF_8)));
return headers;
}
private static byte[] digest(String content, String skey) throws InvalidKeyException, NoSuchAlgorithmException {
byte[] contentBytes = content.getBytes(StandardCharsets.UTF_8);
Mac mac = Mac.getInstance("HMACSHA256");
SecretKeySpec macKey = new SecretKeySpec(skey.getBytes(StandardCharsets.UTF_8), "RAW");
mac.init(macKey);
return mac.doFinal(contentBytes);
}
private static String bytesToHex(byte[] bytes) {
final char[] hexArray = "0123456789ABCDEF".toCharArray();
char[] hexChars = new char[bytes.length * 2];
for (int j = 0; j < bytes.length; j++) {
int v = bytes[j] & 0xFF;
hexChars[j * 2] = hexArray[v >>> 4];
hexChars[j * 2 + 1] = hexArray[v & 0x0F];
}
return new String(hexChars);
}
}
using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
namespace sign
{
public class Sign
{
/**
* Return HTTP Basic Authentication ("Authorization" and "FT-Date") headers.
*
* @param method request HTTP method
* @param host request host string (without port and without the "https://" prefix)
* @param path request path (including query params)
* @param sparams request body parameters stringified
* @param sid Service ID
* @param skey Auth API key
*/
public static Dictionary<string, string> RequestHeaders(string method, string host, string path, string sparams, string serviceID, String skey)
{
string date1 = DateTime.Now.ToString("r").Substring(0, 26);
string date2 = DateTime.Today.ToString("zzz").Replace(":", "");
string date = date1 + date2;
string[] values = new string[] { date, method, host, path, sparams };
StringBuilder data = new StringBuilder();
foreach (string val in values)
{
data.Append(val);
data.Append("\n");
}
string sig = byteArrayToString(Sign.digest(data.ToString(), skey));
string auth = serviceID + ":" + sig;
byte[] authBytes = Encoding.UTF8.GetBytes(auth);
Dictionary<string, string> headers = new Dictionary<string, string>();
headers.Add("FT-Date", date);
headers.Add("Authorization", "Basic " + Convert.ToBase64String(authBytes));
return headers;
}
private static string byteArrayToString(byte[] ba)
{
StringBuilder hex = new StringBuilder(ba.Length * 2);
for (int i = 0; i < ba.Length; i++)
{
hex.AppendFormat("{0:x2}", ba[i]);
}
return hex.ToString();
}
private static byte[] digest(string content, string key)
{
var mac = new HMACSHA256(Encoding.UTF8.GetBytes(key));
return mac.ComputeHash(Encoding.UTF8.GetBytes(content));
}
}
}
/*
* Return HTTP Basic Authentication ("Authorization" and "FT-Date") headers.
* @param1 : method - string : request HTTP method
* @param2 : host - string : request host string (without port and without the "https://" prefix)
* @param3 : path - string : request path (including query params)
* @param4 : params - string : request body parameters stringified
* @param5 : serviceID - string : Service ID
* @param6 : skey - string : Auth API key
*
* return : array : "Authorization" and "FT-Date" headers
*/
function requestHeaders($method, $host, $path, $params, $serviceID, $skey) {
$date = date("D, d M Y H:i:s O");
$values = array($date, $method, $host, $path, $params);
$data = "";
foreach($values as $val) {
$data .= $val . "\n";
}
$sign = hash_hmac("sha256", $data, $skey);
$auth = $serviceID . ":" . $sign;
return array("Authorization: Basic " . base64_encode($auth),
"FT-Date: " . $date);
}
var CryptoJS = require("crypto-js");
/**
* Return HTTP Basic Authentication ("Authorization" and "FT-Date") headers.
*
* @param method request HTTP method
* @param host request host string (without port and without the "https://" prefix)
* @param path request path (including query params)
* @param sparams request body parameters stringified
* @param sid Service ID
* @param skey Auth API key
*/
exports.sign = function(method, host, path, sparams, sid, skey) {
var date = new Date().toUTCString().slice(0,26) + "-0000";
var digestContent = date + "\n" + method + "\n" + host + "\n" + path +"\n" + sparams +"\n";
var sig = CryptoJS.HmacSHA256(digestContent, skey).toString(CryptoJS.enc.Hex).toUpperCase();
var words = CryptoJS.enc.Utf8.parse(sid + ":" + sig);
var auth = CryptoJS.enc.Base64.stringify(words);
return {"Authorization": "Basic " + auth, "FT-Date": date};
};
Component | Description |
---|---|
date | The current time, formatted as RFC 2822 (essentially the content of the FT-Date header). |
HTTP method | The HTTP method (uppercase). |
host | Your Service hostname (lowercase). |
path + query params | The path of the endpoint including any query string parameters if they exist. |
body params | A JSON object containing the body request parameters as key/value pairs. It must be the exact string that will be sent as part of the request. These are the body parameters of POST requests. If the request does not have any body parameters (i.e, it's an empty POST/PUT request or a GET/DELETE request) you must still include one blank line in the string that will be signed. |
This is an example of a POST request showcasing the above components, which are concatenated with newline characters. Note that a newline character is appended after every component, including the last one, i.e., the body params, even if it is empty.
Wed, 03 Aug 2016 13:36:21 -0000 POST xxxxxx.futurae.com /srv/auth/v1/user/enroll {"user_id":"70d63df1-d20d-4530-ac92-aa6f9f6f329e","valid_secs":86400}
After having constructed the concatenated string you can compute the HMAC-SHA256 signature using your Auth API key as the HMAC key. The signature needs to be in hexadecimal ASCII format (i.e., not raw binary).
This is how a full request might look like:
POST /srv/auth/v1/user/enroll HTTP/1.1 FT-Date: Wed, 03 Aug 2016 13:36:21 -0000 Authorization: Basic NzRjY2U2MWMtZWRlYS00OGZmLTg5M2QtNDg2Yzg3MmE0ZDc3OjBmOGIwNmM2ZTQ3MjU5YjNhYjdkMGZlMjhhNTBiMjNjZjQxM2NjODY4MDEwNGZjMzE5YzQ5MDkyMjlkZDQyMjc= Content-Type: application/json Host: xxxxxx.futurae.com Content-Length: 69 {"user_id":"70d63df1-d20d-4530-ac92-aa6f9f6f329e","valid_secs":86400}
IMPORTANT: You should never send your Auth API key as part of the request, rather only use it as an HMAC key to sign the request content.
You can use Test GET Authorization and Test POST Authorization in order to verify that your requests are authenticated properly.
Troubleshooting Request Authentication
In case you are having trouble to correctly authenticate your requests, we provide you with the following help:
When calling Test GET Authorization or Test POST Authorization, whenever the request authentication fails, the Futurae server will include detailed error information in its response, in order to help you identify the cause of the failure.
Below, we provide two step-by-step examples on authenticating an example request. You can use the exact examples in your code and compare all the intermediate outputs with the ones below, in order to identify potential issues.
Example 1: GET Request
Suppose we want to send the following request to the server:
GET https://api-pilot.futurae.com/srv/auth/v1/server/test?testparam=testvalue
Also, suppose that we have the following Service credentials:
- Service ID: 5f21ab85-af2f-11e7-9c0d-784f43834446
- Auth API key: GhYZvjGJVyBgeSXVMyUD5G4YR7Y2PzutGhp/MwUt
And that the date is:
Mon, 16 Oct 2017 12:15:34 -0000
Then, the ASCII string on which the signature must be computed is:
Mon, 16 Oct 2017 12:15:34 -0000\nGET\napi-pilot.futurae.com\n/srv/auth/v1/server/test?testparam=testvalue\n\n
And represented as a byte sequence:
77, 111, 110, 44, 32, 49, 54, 32, 79, 99, 116, 32, 50, 48, 49, 55, 32, 49, 50, 58, 49, 53, 58, 51, 52, 32, 45, 48, 48, 48, 48, 10, 71, 69, 84, 10, 97, 112, 105, 45, 112, 105, 108, 111, 116, 46, 102, 117, 116, 117, 114, 97, 101, 46, 99, 111, 109, 10, 47, 115, 114, 118, 47, 97, 117, 116, 104, 47, 118, 49, 47, 115, 101, 114, 118, 101, 114, 47, 116, 101, 115, 116, 63, 116, 101, 115, 116, 112, 97, 114, 97, 109, 61, 116, 101, 115, 116, 118, 97, 108, 117, 101, 10, 10
Notice the two newline characters at the end, which occurs because the request has an empty body.
The resulting HMAC-SHA256 signature in hexadecimal notation will be:
910ef81f5fcf092d203e77ead93a3896092e4953c9cbb41c3e792e8d0b417168
Then we concatenate this together with the Service ID:
5f21ab85-af2f-11e7-9c0d-784f43834446:910ef81f5fcf092d203e77ead93a3896092e4953c9cbb41c3e792e8d0b417168
And encode in base64:
NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjkxMGVmODFmNWZjZjA5MmQyMDNlNzdlYWQ5M2EzODk2MDkyZTQ5NTNjOWNiYjQxYzNlNzkyZThkMGI0MTcxNjg=
Finally, the resulting request will be:
GET /srv/auth/v1/server/test?testparam=testvalue HTTP/1.1 FT-Date: Mon, 16 Oct 2017 12:15:34 -0000 Authorization: Basic NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjkxMGVmODFmNWZjZjA5MmQyMDNlNzdlYWQ5M2EzODk2MDkyZTQ5NTNjOWNiYjQxYzNlNzkyZThkMGI0MTcxNjg= Host: api-pilot.futurae.com
Example 2: POST Request
Suppose we want to send the following request to the server:
POST https://api-pilot.futurae.com/srv/auth/v1/server/test
with body:
{"testparam":"testvalue"}
Also, suppose that we have the following Service credentials:
- Service ID: 5f21ab85-af2f-11e7-9c0d-784f43834446
- Auth API key: GhYZvjGJVyBgeSXVMyUD5G4YR7Y2PzutGhp/MwUt
And that the date is:
Mon, 16 Oct 2017 12:15:34 -0000
Then, the ASCII string on which the signature must be computed is:
Mon, 16 Oct 2017 12:15:34 -0000\nPOST\napi-pilot.futurae.com\n/srv/auth/v1/server/test\n{"testparam":"testvalue"}\n
And represented as a byte sequence:
77, 111, 110, 44, 32, 49, 54, 32, 79, 99, 116, 32, 50, 48, 49, 55, 32, 49, 50, 58, 49, 53, 58, 51, 52, 32, 45, 48, 48, 48, 48, 10, 80, 79, 83, 84, 10, 97, 112, 105, 45, 112, 105, 108, 111, 116, 46, 102, 117, 116, 117, 114, 97, 101, 46, 99, 111, 109, 10, 47, 115, 114, 118, 47, 97, 117, 116, 104, 47, 118, 49, 47, 115, 101, 114, 118, 101, 114, 47, 116, 101, 115, 116, 10, 123, 34, 116, 101, 115, 116, 112, 97, 114, 97, 109, 34, 58, 34, 116, 101, 115, 116, 118, 97, 108, 117, 101, 34, 125, 10
The resulting HMAC-SHA256 signature in hexadecimal notation will be:
7132afde8b6a3ec25ac3f56ec62c633bde998379688547942248c431d8019b43
Then we concatenate this together with the Service ID:
5f21ab85-af2f-11e7-9c0d-784f43834446:7132afde8b6a3ec25ac3f56ec62c633bde998379688547942248c431d8019b43
And encode in base64:
NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjcxMzJhZmRlOGI2YTNlYzI1YWMzZjU2ZWM2MmM2MzNiZGU5OTgzNzk2ODg1NDc5NDIyNDhjNDMxZDgwMTliNDM=
Finally, the resulting request will be:
POST /srv/auth/v1/server/test HTTP/1.1 FT-Date: Mon, 16 Oct 2017 12:15:34 -0000 Authorization: Basic NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjcxMzJhZmRlOGI2YTNlYzI1YWMzZjU2ZWM2MmM2MzNiZGU5OTgzNzk2ODg1NDc5NDIyNDhjNDMxZDgwMTliNDM= Content-Type: application/json Host: api-pilot.futurae.com Content-Length: 25 {"testparam":"testvalue"}
Callback Authentication
Certain API endpoints, such as Enroll Users and Devices, Authenticate User and Authenticate Transaction, offer the ability to receive results via HTTP POST callbacks. The callback URL needs to be supplied as an input parameter when invoking each relevant endpoint.
Your application must verify the authenticity of each incoming callback request, to ensure that it comes from the Futurae backend. One way to achieve this is to supply a token or nonce (random, high-entropy unguessable value, only used once) as part of the callback URL:
https://www.domain.com/callback?token=alongrandomstringforextrasecurity
JWS Signatures
Moreover, the Auth API offers callback payload verification using detached JWS signatures.
The server uses the Service Callback Signature key (which you can get from Futurae Admin) to compute a JWS signature over the HTTP body payload of the callback, using HS256
(HMAC-SHA256) as the specified algorithm. The detached JWS signature (detached means that the payload representation is missing from the JWS) is appended in the HTTP header x-jws-signature
. For example:
x-jws-signature: eyJhbGciOiJIUzI1NiJ9..NsolKSrrFivUFZx_qixwfrogkrpdkz54QyiWlosngwQ
To verify the JWS signature, perform the following steps:
Step 1. To construct the full (non-detached) JWS signature, convert the request body to URL-safe base64 and insert the resulting string in the correct position in the detached JWS, between the two dots, as illustrated in the example below:
eyJhbGciOiJIUzI1NiJ9.base64url(HTTP_request_body).NsolKSrrFivUFZx_qixwfrogkrpdkz54QyiWlosngwQ
Step 2. Verify the JWS signature using the Callback Signature key, and HS256
as algorithm.
Response Format
All responses are formatted as JSON objects (the header Content-Type: application/json
is always present in the responses).
Successful responses return a HTTP 200 response code and, depending on the endpoint and its parameters, the JSON response will contain the corresponding fields. In some cases, the response might contain nested JSON arrays and/or objects. Refer to each individual endpoint to check the format of the endpoint's successful responses.
This is how an unsuccessful response payload looks like:
{
"error": true,
"code": 40000,
"message": "Bad request"
}
Unsuccessful responses return an appropriate HTTP response code that conveys the high-level reason of the failure, plus a JSON object of a specified format that might supply some additional details regarding the error. In particular, unsuccessful responses will contain an error
boolean field, whose value will be true
. Moreover, the response will contain an integer code
, and a message
field that further describes the failure. A detail
field may be present if additional information is available. Example:
The HTTP response code will be the first three digits of the more specific code
found inside the JSON object.
HTTP Response Codes
Below are listed some common HTTP response codes and their meaning. The codes marked as generic represent generic error codes and could be returned by any endpoint even if they are not explicitly listed in the description of some endpoints.
HTTP Code | Meaning | Generic |
---|---|---|
200 |
The request was successful. The only code which indicates that the request was processed successfully. | |
400 |
Invalid or missing request parameters. | yes |
401 |
Authorization data is missing or invalid. | yes |
403 |
The request is currently forbidden and cannot be fulfilled for the specified parameters. | |
404 |
The requested endpoint does not exist. | |
405 |
The request HTTP method is not valid for this endpoint (for example, POST when only GET is supported). | yes |
429 |
The account has made too many requests of this type recently. Try again later. | yes |
500 |
An unexpected, internal server error occurred. | yes |
501 |
The requested endpoint or the way of calling a particular endpoint is not yet functional (unimplemented feature). | yes |
End-to-end encryption for extra_info
Futurae Authenticate User and Authenticate Transaction endpoints support extra_info
data End-to-End encryption:
- The Customer backend encrypts the
extra_info
and the send it encrypted to Futurae backend. - The mobile application receives the encrypted
extra_info
from the Futurae backend, and decrypts it
If End-to-End encryption is enabled for your Service, authentication contextual information can be provided to Futurae in the encrypted format. For that, set the extra_info_format
attribute value as jwe
, and encrypt the extra_info
content before providing it Futurae when starting an authentication.
If extra_info_format
attribute is not specified, or set as plain_text_array
, the extra_info
content needs to be provided in plain JSON format.
Endpoints supporting extra_info
data end-to-end encryption
- Authenticate with One-Touch
- Authenticate with Mobile Auth
- Authenticate with QR Code
- Authenticate with Offline QR Code
- Authenticate with Usernameless QR Code
- Authenticate Transaction with One
- Authenticate Transaction with QR Code
- Authenticate Transaction with Offline QR Code
- Authenticate Transaction with Mobile Auth
Symmetric key
A base64 encoded symmetric key extra_info_key
can be found at Futurae Admin. This key is used to encrypt the extra_info
content, according to the steps described in the extra_info
encryption procedure section.
The extra_info_key
is a Service level key, in other words, every Futurae Service has a distinct extra_info_key
.
extra_info
encryption procedure
This is the outline of the extra_info
encryption procedure:
- Serialize the unencrypted
extra_info
into a JSON formatted string. - Decode the base64 encoded
extra_info_key
. - Create the JWE Compact Serialization of the unencrypted
extra_info
JSON formatted string, which represents encrypted content as a compact, URL-safe string. - Provide the string resulting of the previous step, as content of the
extra_info
field, and set the fieldextra_info_format
value tojwe
.
Parallel Requests Confirmations
By default, the Futurae API allows a single authentication or transaction signing session simultaneously, per Futurae user. When a new authentication or transaction singing session is created for a Futurae user, any existing pending sessions for the same User are automatically canceled with authentication result deny
and authentication status interrupted
.
With Parallel Requests Confirmations feature enabled, it is therefore possible to manage parallel on-going Authenticate User or Authenticate Transaction sessions, allowing a more dynamic interaction where multiple operations may be waiting for user approval in parallel. Parallel Requests Confirmations is supported by Futurae Mobile SDKs, and by Futurae Access apps by request.
This feature can be combined with Extended Confirmation Validity functionality, in order to extend the session maximum validity for up to one hour.
Server
Endpoints related to testing communication with the Futurae server.
Ping Server
GET /srv/auth/v1/server/ping
This endpoint can be called to verify that the Futurae server is up. Note that this endpoint does not have to be authenticated with the Authorization
header.
Response 200
Example response:
200 OK
{
"time": "1461694259294"
}
Request was successful.
Fields | |
---|---|
timestring
|
Unix epoch time in milliseconds. |
Get API Version
GET /srv/auth/v1/server/api_version
This endpoint can be called in order to retrieve the version of the Futurae Auth API that this server runs. Note that this endpoint does not have to be authenticated with the Authorization
header.
Response 200
Example response:
200 OK
{
"api_version": "1.0.0"
}
Request was successful.
Fields | |
---|---|
api_versionstring
|
Futurae Auth API version that this server runs. |
Test GET Authorization
Example request query params:
dummy_param=dummy_value&another_param=some_value
GET /srv/auth/v1/server/test
This endpoint can be called in order to verify that the authorization for GET requests is properly implemented and working as expected. For the purposes of testing, you can optionally add dummy URL query parameters.
Response 200
Example response:
200 OK
{
"time": "1461694259294"
}
Request was successful.
Fields | |
---|---|
timestring
|
Unix epoch time in milliseconds. |
Response 401
Example response:
401 Unauthorized
{
"error": true,
"code": 40100,
"message": "authorization data missing or invalid",
"detail": "Authorization failed. HMAC verification failed:\n--DEBUG INFO START--\n----CONTENT TO BE SIGNED----\nTue, 20 Nov 2018 09:34:29 +0100\nGET\napi.futurae.com\n/srv/auth/v1/server/test\n\n-----CONTENT BYTES------\n[84 117 101 44 32 50 48 32 78 111 118 32 50 48 49 56 32 48 57 58 51 52 58 50 57 32 43 48 49 48 48 10 71 69 84 10 97 112 105 46 102 117 116 117 114 97 101 46 99 111 109 10 47 115 114 118 47 97 117 116 104 47 118 49 47 115 101 114 118 101 114 47 116 101 115 116 10 10]\n--DEBUG INFO END--"
}
Authorization failure. The response body will contain additional information in order to help you identify the reason of the failure.
Test POST Authorization
Example request body params:
{
"dummy_param": "dummy_value"
}
POST /srv/auth/v1/server/test
This endpoint can be called in order to verify that the authorization for POST requests is properly implemented and working as expected. For the purposes of testing, you can optionally add dummy, JSON-formatted, body parameters.
Response 200
Example response:
200 OK
{
"time": "1461694259294"
}
Request was successful.
Fields | |
---|---|
timestring
|
Unix epoch time in milliseconds. |
Response 401
Example response:
401 Unauthorized
{
"error": true,
"code": 40100,
"message": "authorization data missing or invalid",
"detail": "Authorization failed. HMAC verification failed:\n--DEBUG INFO START--\n----CONTENT TO BE SIGNED----\nTue, 20 Nov 2018 09:34:29 +0100\nGET\napi.futurae.com\n/srv/auth/v1/server/test\n\n-----CONTENT BYTES------\n[84 117 101 44 32 50 48 32 78 111 118 32 50 48 49 56 32 48 57 58 51 52 58 50 57 32 43 48 49 48 48 10 71 69 84 10 97 112 105 46 102 117 116 117 114 97 101 46 99 111 109 10 47 115 114 118 47 97 117 116 104 47 118 49 47 115 101 114 118 101 114 47 116 101 115 116 10 10]\n--DEBUG INFO END--"
}
Authorization failure. The response body will contain additional information in order to help you identify the reason of the failure.
Service
Endpoints related to Service account information and configuration.
Get Stored Logo
GET /srv/auth/v1/service/logo
Get a direct download URL of the logo which is displayed in the Futurae mobile app.
Response 200
Example response:
200 OK
{
"logo_url": "https://api.futurae.com/logos/YZDHoB-GQhS4SQ37k8iaWqSXshNvwekrw36MbdqZzLSH7L5b7IRkdw=="
}
Request was successful.
Fields | |
---|---|
logo_urlstring
|
The URL from which the logo can be downloaded. |
Response 404
Example response:
404 Not Found
{
"error": true,
"code": 40100,
"message": "not found"
}
No logo is currently stored on Futurae. Use Upload New Logo to upload a logo.
Upload New Logo
POST /srv/auth/v1/service/logo
Upload a new logo to display in the Futurae mobile app. The previously uploaded logo, if any, will be deleted and replaced by the new logo.
Body Parameters
Example request body params:
{
"logo": "iVBORw0KGgoAAAANSU...(truncated)...bJP/DxeklQAAAABJRU5ErkJggg=="
}
logostring required |
The PNG image data in Base 64 encoding. |
Response 200
Example response:
200 OK
{
"logo_url": "https://api.futurae.com/logos/YZDHoB-GQhS4SQ37k8iaWqSXshNvwekrw36MbdqZzLSH7L5b7IRkdw=="
}
Request was successful.
Fields | |
---|---|
logo_urlstring
|
The URL from which the logo can be downloaded. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Missing or invalid parameters.
Retrieve Pending Enrollments
GET /srv/auth/v1/service/pending_enrollments
This endpoint can be used to retrieve information about all the pending enrollments (created via Enroll Users and Devices and not yet completed) during a specified time range. The results are returned in batches of 50 enrollments. The offset
parameter can be used to retrieve all the results, by calling this endpoint multiple times with the appropriate offset
parameter values.
Query Parameters
Example request query params:
begin=1497188000&end=1497188999&offset=0
beginnumber required |
Begin of the time range formatted as a Unix timestamp in seconds. |
endnumber required |
End of the time range formatted as a Unix timestamp in seconds. |
offsetnumber required |
Offset of first result. 0 : return results 0 - 49. 50 : return results 50 - 99. Keep increasing by 50 until no results are returned. |
Response 200
Example response:
200 OK
{
"enrollments":[
{
"activation_code": "Tf9T5Cl1ffnkDSiD0AmWizbSxxHABbIsYr3bMn14HYU=",
"activation_code_uri": "futurae://enroll?activation_code=Tf9T5Cl1ffnkDSiD0AmWizbSxxHABbIsYr3bMn14HYU=",
"activation_universal_link": "https://futurae.com/futurae_enroll?activation_code=Tf9T5Cl1ffnkDSiD0AmWizbSxxHABbIsYr3bMn14HYU=",
"activation_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"activation_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?enroll=Tf9T5Cl1ffnkDSiD0AmWizbSxxHABbIsYr3bMn14HYU=",
"creation": 1497188739,
"expiration": 1497275140,
"user_id": "4176549f-4eac-11e7-88d8-c241ed9b4fdd",
"username": "2k9XxrwscVlpczOraIQJgfHfJTRLZ19uXNCXlzPh8pg=",
"enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002"
},
{
"activation_code": "JyEBs1p4JyCU6p0GEJ-mhKgaUIw3ny0t4R6FTNRrf10=",
"activation_code_short": "o2nf aoxi 1bxy wo71",
"activation_code_uri": "futurae://enroll?activation_code=JyEBs1p4JyCU6p0GEJ-mhKgaUIw3ny0t4R6FTNRrf10=",
"activation_universal_link": "https://futurae.com/futurae_enroll?activation_code=JyEBs1p4JyCU6p0GEJ-mhKgaUIw3ny0t4R6FTNRrf10=",
"activation_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"activation_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?enroll=JyEBs1p4JyCU6p0GEJ-mhKgaUIw3ny0t4R6FTNRrf10=",
"creation": 1497188791,
"expiration": 1497275191,
"user_id": "6011731c-4eac-11e7-88d8-c241ed9b4fdd",
"username": "SWJxnclWdGwMr8G1rUxfnL7HCeLJchh-Ckuitsw-m9Q=",
"enrollment_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6"
}
]
}
Request was successful.
The response is a JSON object containing an array of objects, one for each individual enrollment.
The fields contained in these objects are identical to the ones returned by Enroll Users and Devices, with the addition of a creation
field which is the time at which this enrollment was created (formatted as a Unix timestamp in seconds).
The array will be empty if no pending enrollments are found for the specified time range and offset.
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Missing or invalid parameters.
Users and Devices
Endpoints related to user and device management.
Enroll Users and Devices
POST /srv/auth/v1/user/enroll
This endpoint provides a programmatic way to enroll new users and devices with Futurae authentication. There are several distinct enrollment cases, depending on whether you wish to enroll a new user and device, or a device for an existing user, and on the type of device.
Enroll New User with Mobile Device
POST /srv/auth/v1/user/enroll
Create a new user in Futurae and at the same time get an activation code in order to activate a mobile device for this user. In particular, this endpoint invocation will return an activation code as a QR code PNG image (also as a clickable URI) that the Futurae mobile app can scan using the mobile device's built-in camera. Scanning the QR code activates the particular device for the specific user.
Body Parameters
Example request body params:
{
"username": "someuser@domain.com",
"display_name": "Some User",
"valid_secs": 3600,
"success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity",
"enrollment_flow_binding_enabled": false,
"account_recovery_flow_binding_enabled": false
}
usernamestring optional |
Unique username for the newly created user. This can serve as an application-specified unique identifier for the user. If not supplied, a random username will be assigned and returned. See the input restrictions that apply. |
display_namestring optional |
An optional display name, which is displayed in the user's Futurae mobile app. As an example, it could be the user's email address. If not supplied, the display name will be empty. See the input restrictions that apply. |
valid_secsnumber optional |
Time, in seconds, for which the activation code will remain valid. Minimum: 60 Maximum: 7776000 (90 days)Default: 604800 (7 days) |
short_codeboolean optional |
Set this field to true if you require a short activation code to be included in the response. A short activation code is suitable for manual user entry in the app, and is useful in case the user's phone has a malfunctioning camera or if the user does not want to give the app permission to access the camera.Default: false
|
success_callback_urlstring optional |
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. This is an alternative to using Enroll Status. The URL will be called as a POST request with Content-Type header being application/json . The body of the request will be a JSON object containing the following fields and corresponding values: user_id , username , activation_code , device_id and result . The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
enrollment_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for this enrollment.Default: false
|
account_recovery_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for account recovery.Default: false
|
Response 200
Example response:
200 OK
{
"activation_code": "MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
"enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
"activation_code_uri": "futurae://enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
"activation_universal_link": "https://futurae.com/futurae_enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
"activation_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"activation_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?enroll=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
"expiration": 1461694259,
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"username": "someuser@domain.com"
}
Request was successful.
Fields | |
---|---|
activation_codestring
|
The activation code. |
enrollment_idstring
|
Enrollment unique ID. |
activation_qrcode_urlstring
|
URL for a PNG image of a scannable QR code with the activation code. This is useful when the user attempts to enable Futurae authentication by accessing his account from a device different than the one on which the Futurae mobile app is installed, for example, when accessing his account from a desktop/laptop computer. Note that the URL is directly accessible (i.e., no Authorization header needed). |
activation_qrcode_data_uristring
|
PNG image of a scannable QR code containing the activation code in data URI scheme. This is the same QR code image that can be retrieved via activation_qrcode_url .
|
activation_code_uristring
|
The activation code in the form of a URI prefixed with the SDK/app scheme, this would be futurae:// for the Futurae mobile app. On phones with the Futurae mobile app already installed, it will be a clickable link. This is mostly useful when the user attempts to enable Futurae authentication directly from the device on which the Futurae mobile app is installed (e.g., the URI can be sent via email to be opened directly on the mobile device where the Futurae mobile app is installed and about to be activated). |
activation_universal_linkstring
|
Similar to activation_code_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
activation_code_shortstring
|
If short_code was set to true , then this field contains the short activation code, suitable for manual user entry. Otherwise this field is not contained in the response. |
expirationnumber
|
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds). |
user_idstring
|
Permanent, unique identifier for the user in Futurae. Always generated by Futurae. |
usernamestring
|
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or a user with the specified username
already exists.
Enroll New Mobile Device for Existing User
POST /srv/auth/v1/user/enroll
This endpoint invocation returns an activation code as a QR code PNG image (also as a clickable URI) in order to activate a mobile device for an existing Futurae user. The Futurae mobile app can scan the QR code using the mobile device's built-in camera. Scanning the QR code activates the particular device for the specific user.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"valid_secs": 3600,
"success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity",
"enrollment_flow_binding_enabled": false,
"account_recovery_flow_binding_enabled": false
}
user_idstring required |
The permanent, unique ID of the user as generated by Futurae. |
valid_secsnumber optional |
Time, in seconds, for which the activation code will remain valid. Minimum: 60 Maximum: 7776000 (90 days)Default: 604800 (7 days) |
short_codeboolean optional |
Set this field to true if you require a short activation code to be included in the response. A short activation code is suitable for manual user entry in the app, and is useful in case the user's phone has a malfunctioning camera or if the user does not want to give the app permission to access the camera.Default: false
|
success_callback_urlstring optional |
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. This is an alternative to using Enroll Status. The URL will be called as a POST request with Content-Type header being application/json . The body of the request will be a JSON object containing the following fields and corresponding values: user_id , username , activation_code , device_id and result . The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
enrollment_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for this enrollment.Default: false
|
account_recovery_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for account recovery.Default: false
|
Response 200
Example response:
200 OK
{
"activation_code": "bXR3SExHMERlMHJlQ1pRWmFxcGwwQmxSRWZUd3dmS2VvOGU4dWpEZlIxdzplM2YyOWQ5Zi04MjRkLTQ4N2ItODg5MS0zZmI5NTY4NTE4YjI6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
"enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
"activation_code_uri": "futurae://enroll?activation_code=bXR3SExHMERlMHJlQ1pRWmFxcGwwQmxSRWZUd3dmS2VvOGU4dWpEZlIxdzplM2YyOWQ5Zi04MjRkLTQ4N2ItODg5MS0zZmI5NTY4NTE4YjI6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
"activation_universal_link": "https://futurae.com/futurae_enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
"activation_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"activation_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?enroll=bXR3SExHMERlMHJlQ1pRWmFxcGwwQmxSRWZUd3dmS2VvOGU4dWpEZlIxdzplM2YyOWQ5Zi04MjRkLTQ4N2ItODg5MS0zZmI5NTY4NTE4YjI6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
"expiration": 1543080538,
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"username": "someuser@domain.com"
}
Request was successful.
Fields | |
---|---|
activation_codestring
|
The activation code. |
enrollment_idstring
|
Enrollment unique ID. |
activation_qrcode_urlstring
|
URL for a PNG image of a scannable QR code with the activation code. This is useful when the user attempts to enable Futurae authentication by accessing his account from a device different than the one on which the Futurae mobile app is installed, for example, when accessing his account from a desktop/laptop computer. Note that the URL is directly accessible (i.e., no Authorization header needed). |
activation_qrcode_data_uristring
|
PNG image of a scannable QR code containing the activation code in data URI scheme. This is the same QR code image that can be retrieved via activation_qrcode_url .
|
activation_code_uristring
|
The activation code in the form of a URI prefixed with the SDK/app scheme, this would be futurae:// for the Futurae mobile app. On phones with the Futurae mobile app already installed, it will be a clickable link. This is mostly useful when the user attempts to enable Futurae authentication directly from the device on which the Futurae mobile app is installed (e.g., the URI can be sent via email to be opened directly on the mobile device where the Futurae mobile app is installed and about to be activated). |
activation_universal_linkstring
|
Similar to activation_code_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
activation_code_shortstring
|
If short_code was set to true , then this field contains the short activation code, suitable for manual user entry. Otherwise this field is not contained in the response. |
expirationnumber
|
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds). |
user_idstring
|
Permanent, unique identifier for the user in Futurae. Always generated by Futurae. |
usernamestring
|
Unique identifier for the user in Futurae. Either specified as a parameter upon user creation or auto-generated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the supplied user_id
does not exist.
Enroll New User with FIDO Device
POST /srv/auth/v1/user/enroll
Create a new user in Futurae and at the same time get an activation code in order to enroll a FIDO device for this user. The activation code can be returned in two forms, default (long) and short, and has to be passed as argument when calling WebAuthnJS SDK's enroll() method, in order to start the activation process on the client side. You can use the activation code in two different ways for enrolling the FIDO device:
- Implicit: Pass the activation code to WebAuthnJS SDK's enroll() method in the background. The user will be able to activate his FIDO authenticator, being completely unaware of the activation code. This approach assumes that the enrollment process is sufficiently authenticated and/or attacker-free.
-
Explicit: Get a short version of the activation code by supplying the
short_code
input param astrue
. Deliver the short activation code to the user using an out-of-band channel. When the user is about to activate his FIDO device, ask the user to supply the code and pass the supplied value to WebAuthnJS SDK's enroll() method. This approach increases the security of the FIDO registration step, and is useful when the activation process is not sufficiently authenticated or the risk that the attacker might be able to hijack the activation process is not acceptable.
Body Parameters
Example request body params:
{
"username": "someuser@domain.com",
"display_name": "Some User",
"fido": true,
"valid_secs": 3600,
"authenticator_selection": {
"user_verification": "required"
},
"success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity",
"enrollment_flow_binding_enabled": false,
"account_recovery_flow_binding_enabled": false
}
usernamestring optional |
Unique username for the newly created user. This can serve as an application-specified unique identifier for the user. If not supplied, a random username will be assigned and returned. See the input restrictions that apply. |
display_namestring optional |
An optional display name, which is displayed in the user's Futurae mobile app. As an example, it could be the user's email address. If not supplied, the display name will be empty. See the input restrictions that apply. |
fidoboolean required |
This field must be set to true , in order to enroll a FIDO device. |
valid_secsnumber optional |
Time, in seconds, for which the activation code will remain valid. Minimum: 60 Maximum: 7776000 (90 days)Default: 604800 (7 days) |
short_codeboolean optional |
Set this field to true if you require a short activation code to be included in the response. A short activation code is suitable for delivering to the user and requiring them to supply it during the FIDO registration process (as explained in the explicit approach above).Default: false
|
attestation_preferencestring optional |
Supply this field to override the Relying Party's default Attestation Conveyance Preference. Refer to the WebAuthn RP Configuration resource for a detailed description. |
authenticator_selectionobject optional |
Supply this field to override the Relying Party's default Authenticator Selection Criteria. Refer to the WebAuthn RP Configuration resource for a detailed description. |
success_callback_urlstring optional |
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. This is an alternative to using Enroll Status. The URL will be called as a POST request with Content-Type header being application/json . The body of the request will be a JSON object containing the following fields and corresponding values: user_id , username , activation_code , device_id and result . The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
enrollment_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for this enrollment.Default: false
|
account_recovery_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for account recovery.Default: false
|
Response 200
Example response:
200 OK
{
"activation_code": "NUhiSXk4eF9LRVE3SXdFZDZvRmVUeFd4Qy1BWGtPUlJZX1JnM0ctZm1EQWk6N2E3ZjUyMDktZWUwOS00ZDU0LThlYzAtY2Y2MTAyYjVmNGI2OmFwaS10ZXN0LmZ1dHVyYWUuY29t",
"enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
"activation_code_short": "vr50 7gia qpsi qg8e",
"expiration": 1461694259,
"user_id": "7a7f5209-ee09-4d54-8ec0-cf6102b5f4b6",
"username": "someuser@domain.com"
}
Request was successful.
Fields | |
---|---|
activation_codestring
|
The activation code. Suitable for use in the implicit approach explained above. |
enrollment_idstring
|
Enrollment unique ID. |
activation_code_shortstring
|
If short_code was set to true , then this field contains the short form of the activation code, otherwise this field is not contained in the response. The short activation code is suitable for the explicit approach explained above. |
expirationnumber
|
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds). |
user_idstring
|
Permanent, unique identifier for the user in Futurae. Always generated by Futurae. |
usernamestring
|
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or a user with the specified username
already exists.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
This operation is not permitted because the Service doesn't have an associated WebAuthn RP Configuration. Call Admin API's Create RP Configuration to create it.
Enroll New FIDO Device for Existing User
POST /srv/auth/v1/user/enroll
This endpoint returns an activation code in order to enroll a FIDO device for an existing Futurae user. The activation code can be returned in two forms, default (long) and short, and has to be passed as argument when calling WebAuthnJS SDK's enroll() method, in order to start the activation process on the client side. You can use the activation code in two different ways for enrolling the FIDO device:
- Implicit: Pass the activation code to WebAuthnJS SDK's enroll() method in the background. The user will be able to activate his FIDO authenticator, being completely unaware of the activation code. This approach assumes that the enrollment process is sufficiently authenticated and/or attacker-free.
-
Explicit: Get a short version of the activation code by supplying the
short_code
input param astrue
. Deliver the short activation code to the user using an out-of-band channel. When the user is about to activate his FIDO device, ask the user to supply the code and pass the supplied value to WebAuthnJS SDK's enroll() method. This approach increases the security of the FIDO registration step, and is useful when the activation process is not sufficiently authenticated or the risk that the attacker might be able to hijack the activation process is not acceptable.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"fido": true,
"valid_secs": 3600,
"authenticator_selection": {
"user_verification": "required"
},
"success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity",
"enrollment_flow_binding_enabled": false,
"account_recovery_flow_binding_enabled": false
}
user_idstring required |
The permanent, unique ID of the user as generated by Futurae. |
fidoboolean required |
This field must be set to true , in order to enroll a FIDO device. |
valid_secsnumber optional |
Time, in seconds, for which the activation code will remain valid. Minimum: 60 Maximum: 7776000 (90 days)Default: 604800 (7 days) |
short_codeboolean optional |
Set this field to true if you require a short activation code to be included in the response. A short activation code is suitable for delivering to the user and requiring them to supply it during the FIDO registration process (as explained in the explicit approach above).Default: false
|
attestation_preferencestring optional |
Supply this field to override the Relying Party's default Attestation Conveyance Preference. Refer to the WebAuthn RP Configuration resource for a detailed description. |
authenticator_selectionobject optional |
Supply this field to override the Relying Party's default Authenticator Selection Criteria. Refer to the WebAuthn RP Configuration resource for a detailed description. |
success_callback_urlstring optional |
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. This is an alternative to using Enroll Status. The URL will be called as a POST request with Content-Type header being application/json . The body of the request will be a JSON object containing the following fields and corresponding values: user_id , username , activation_code , device_id and result . The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
enrollment_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for this enrollment.Default: false
|
account_recovery_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for account recovery.Default: false
|
Response 200
Example response:
200 OK
{
"activation_code": "NUhiSXk4eF9LRVE3SXdFZDZvRmVUeFd4Qy1BWGtPUlJZX1JnM0ctZm1EQWk6N2E3ZjUyMDktZWUwOS00ZDU0LThlYzAtY2Y2MTAyYjVmNGI2OmFwaS10ZXN0LmZ1dHVyYWUuY29t",
"enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
"activation_code_short": "vr50 7gia qpsi qg8e",
"expiration": 1461694259,
"user_id": "7a7f5209-ee09-4d54-8ec0-cf6102b5f4b6",
"username": "someuser@domain.com"
}
Request was successful.
Fields | |
---|---|
activation_codestring
|
The activation code. Suitable for use in the implicit approach explained above. |
enrollment_idstring
|
Enrollment unique ID. |
activation_code_shortstring
|
If short_code was set to true , then this field contains the short form of the activation code, otherwise this field is not contained in the response. The short activation code is suitable for the explicit approach explained above. |
expirationnumber
|
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds). |
user_idstring
|
Permanent, unique identifier for the user in Futurae. Always generated by Futurae. |
usernamestring
|
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the supplied user_id
does not exist.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
This operation is not permitted because the Service doesn't have an associated WebAuthn RP Configuration. Call Admin API's Create RP Configuration to create it.
Enroll New User with Hardware Token
POST /srv/auth/v1/user/enroll
Create a new user in Futurae and at the same time assign a hardware Token to them. The assignment creates a new device record for this user.
Body Parameters
Example request body params:
{
"username": "someuser@domain.com",
"display_name": "Some User",
"hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10"
}
usernamestring optional |
Unique username for the newly created user. This can serve as an application-specified unique identifier for the user. If not supplied, a random username will be assigned and returned. See the input restrictions that apply. |
display_namestring optional |
An optional display name, which is displayed in the user's Futurae mobile app. As an example, it could be the user's email address. If not supplied, the display name will be empty. See the input restrictions that apply. |
hwtoken_idstring required |
The ID of the Hardware Token that will be enrolled for this user. |
hwtoken_passcodestring optional |
If hwtoken_id is a TOTP hardware token, you can optionally supply the current TOTP value for verification. If a TOTP value is indeed supplied and verification fails, then this enrollment will not succeed.This is useful in case the TOTP token enrollment process is delegated to the end users themselves. In such a case, you can ask the user to supply the current value of the TOTP token they are attempting to enroll for themselves, in order to verify that they indeed have access to the claimed token. |
Response 200
Example response:
200 OK
{
"device_id": "d8f517c4-295d-4b02-897b-7cadd56abc54",
"user_id": "40de80c1-68fe-42ba-b68e-2152940dbf31",
"username": "someuser@domain.com"
}
Request was successful.
Fields | |
---|---|
device_idstring
|
The ID of the newly created hardware token device. |
user_idstring
|
Permanent, unique identifier for the user in Futurae. Always generated by Futurae. |
usernamestring
|
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Example response (TOTP verification failed):
400 Bad Request
{
"error": true,
"code": 40050,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters.
- A user with the specified
username
already exists. - The specified
hwtoken_id
does not exist or has been archived. - The specified
hwtoken_id
cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization. In this case, thecode
field within the JSON response will have the value40051
. - The supplied
hwtoken_passcode
verification failed against the specifiedhwtoken_id
. In this case, thecode
field within the JSON response will have the value40050
.
Enroll New Hardware Token for Existing User
POST /srv/auth/v1/user/enroll
Assign a hardware Token to an existing user in Futurae. The assignment creates a new device record for this user.
Body Parameters
Example request body params:
{
"user_id": "40de80c1-68fe-42ba-b68e-2152940dbf31",
"hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10"
}
user_idstring required |
The permanent, unique ID of the user as generated by Futurae. |
hwtoken_idstring required |
The ID of the Hardware Token that will be enrolled for this user. |
hwtoken_passcodestring optional |
If hwtoken_id is a TOTP hardware token, you can optionally supply the current TOTP value for verification. If a TOTP value is indeed supplied and verification fails, then this enrollment will not succeed.This is useful in case the TOTP token enrollment process is delegated to the end users themselves. In such a case, you can ask the user to supply the current value of the TOTP token they are attempting to enroll for themselves, in order to verify that they indeed have access to the claimed token. |
Response 200
Example response:
200 OK
{
"device_id": "d8f517c4-295d-4b02-897b-7cadd56abc54",
"user_id": "40de80c1-68fe-42ba-b68e-2152940dbf31",
"username": "someuser@domain.com"
}
Request was successful.
Fields | |
---|---|
device_idstring
|
The ID of the newly created hardware token device. |
user_idstring
|
Permanent, unique identifier for the user in Futurae. Always generated by Futurae. |
usernamestring
|
Unique identifier for the user in Futurae. Either specified as a parameter upon user creation or auto-generated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Example response (TOTP verification failed):
400 Bad Request
{
"error": true,
"code": 40050,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters.
- The specified
hwtoken_id
does not exist or has been archived. - The specified
hwtoken_id
cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization. In this case, thecode
field within the JSON response will have the value40051
. - The supplied
hwtoken_passcode
verification failed against the specifiedhwtoken_id
. In this case, thecode
field within the JSON response will have the value40050
.
Enroll New User with SMS Device
POST /srv/auth/v1/user/enroll
Create a new user in Futurae and at the same time register his phone number in order to activate it for SMS-based authentication. Note that the phone number has to be verified before being able to send SMS one-time codes for authentication. This can be achieved with SMS Device Activation.
Body Parameters
Example request body params:
{
"username": "someuser@domain.com",
"display_name": "Some User",
"phone_number": "+41123456789"
}
usernamestring optional |
Unique username for the newly created user. This can serve as an application-specified unique identifier for the user. If not supplied, a random username will be assigned and returned. See the input restrictions that apply. |
display_namestring optional |
An optional display name, which is displayed in the user's Futurae mobile app. As an example, it could be the user's email address. If not supplied, the display name will be empty. See the input restrictions that apply. |
phone_numberstring required |
The phone number of the device in international format. |
trusted_phone_numberbool optional |
Set this parameter to true to activate the SMS Device and skip the verification process for the phone number. Default: false
|
Response 200
Example response:
200 OK
{
"device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"username": "someuser@domain.com"
}
Request was successful.
Fields | |
---|---|
device_idstring
|
Device ID of the newly created SMS device that has the SMS capability. Use the supplied device ID with SMS Device Activation in order to verify the phone number and make it eligible for SMS-based authentication. |
user_idstring
|
Permanent, unique identifier for the user in Futurae. Always generated by Futurae. |
usernamestring
|
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40001,
"message": "invalid phone number"
}
Invalid or missing parameters. In particular, if the supplied phone_number
is invalid, the code
field within the JSON response will have the value 40001
. The response in such a case is shown in the example.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40303,
"message": "no SMS sender name set"
}
Your subscription does not include the ability to use SMS-based authentication. If you want to be able to use this functionality, please contact sales@futurae.com.
Enroll New SMS Device for Existing User
POST /srv/auth/v1/user/enroll
Register a new phone number for an existing user in order to activate it for SMS-based authentication. Note that the phone number has to be verified before being able to send SMS one-time codes for authentication. This can be achieved with SMS Device Activation.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"phone_number": "+41123456789"
}
user_idstring required |
The permanent, unique ID of the user as generated by Futurae. |
phone_numberstring required |
The phone number of the device in international format. |
trusted_phone_numberbool optional |
Set this parameter to true to activate the SMS Device and skip the verification process for the phone number. Default: false
|
Response 200
Example response:
200 OK
{
"device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"username": "someuser@domain.com"
}
Request was successful.
Fields | |
---|---|
device_idstring
|
Device ID of the newly created SMS device that has the SMS capability. Use the supplied device ID with SMS Device Activation in order to verify the phone number and make it eligible for SMS-based authentication. |
user_idstring
|
Permanent, unique identifier for the user in Futurae. Always generated by Futurae. |
usernamestring
|
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40001,
"message": "invalid phone number"
}
Invalid or missing parameters, or the supplied phone_number
is already registered for this user. In particular, if the supplied phone_number
is invalid, the code
field within the JSON response will have the value 40001
. The response in such a case is shown in the example.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40303,
"message": "no SMS sender name set"
}
Your subscription does not include the ability to use SMS-based authentication. If you want to be able to use this functionality, please contact sales@futurae.com.
Enroll Status
POST /srv/auth/v1/user/enroll_status
Check whether a user has completed enrollment with the Futurae mobile app. Note that the endpoint returns immediately with the current enrollment status, thus you would need to use this endpoint in a poll-based fashion, in order to get informed about a status update. If polling is necessary, we strongly recommend polling no faster than every 1-3 seconds.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
enrollment_id OR activation_code string required |
The enrollment ID as returned in the enrollment_id field contained in the response of Enroll Users and Devices.OR The activation code as returned in the activation_code field contained in the response of Enroll Users and Devices.
|
Response 200
Example response:
200 OK
{
"result": "success",
"device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd"
}
Request was successful.
Fields | |
---|---|
resultstring
|
Status of the enrollment. It will be one of the values described in Enrollment Status. |
device_idstring
|
If result is success , then this field will contain the device ID of the device that got enrolled with the specified activation_code .In all other cases it will be an empty string. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the specified user_id
and activation_code
combination does not exist.
SMS Device Activation
POST /srv/auth/v1/user/sms_activation
Verify a newly registered phone number (registered via Enroll Users and Devices). This endpoint has to be called at least two times: Once in order to send an SMS activation code to the registered device, and once in order to verify the user supplied code. This endpoint can be called multiple times if necessary, until the phone number is successfully verified and the respective device can be used for authentication (for example in case the SMS does not arrive, you can retry sending another SMS). There is a limit of ten incorrect attempts to verify the SMS. If that limit is reached the user will become locked_out
.
Body Parameters
Example request body params:
To send the activation code via SMS:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
"action": "send",
"sms_text": "Your awesome activation code is"
}
To verify the activation code that the user supplied:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
"action": "verify",
"passcode": "495278"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
device_idstring required |
The device ID, as returned from Enroll Users and Devices. |
actionstring required |
If the value is send then the Futurae server will send an activation code over SMS to the registered phone number). Your application needs to subsequently call this endpoint once again with a different action in order to verify the passcode supplied by the user. The activation code will have an expiration time of 5 minutes.If the value is verify then Futurae will check if the user supplied passcode matches the one sent over SMS to the user's phone. |
sms_textstring optional |
When action is send , the default text contained in the SMS is:Your activation code is , followed by a space character and the activation code. If you want to change the default text, you can supply this parameter with the text of your choice. If the placeholder $OTP is present on the message it is replaced by the activation code and it won't be included at the end of the message.Maximum length: If characters outside the GSM-7 character set are used, the maximum length is 60 characters. Otherwise, the maximum length is 153 characters, except if the message contains the characters ^{}[]~|€ which are counted as 2 characters each.
|
passcodestring required if action is verify
|
When action is verify , this is the user supplied passcode that needs to be verified.
|
Response 200
Example response:
200 OK
{
"result": "sent"
}
Request was successful.
Fields | |
---|---|
resultstring
|
The result of calling the endpoint. It can have one of the following values:sent — The SMS verification passcode was sent to the user's device. Applicable only when action parameter is send .success — The user supplied passcode was correct. The device id with the respective phone number is considered valid and eligible to use for authentication. Applicable only when action parameter is verify .failure — The user supplied passcode was not the expected one. The user can retry typing the passcode and your application can call this endpoint once again to verify the new code. Alternatively, your application can choose to call this endpoint in order to send a fresh verification SMS to the user's device. Applicable only when action parameter is verify .already_enrolled — The supplied device is already enrolled. No action was taken. There is no point in calling this endpoint for this device anymore. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the specified user_id
and device_id
combination does not exist, or the device_id
is not a valid SMS-enabled device, or the user is currently locked out.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40303,
"message": "no SMS sender name set"
}
The action
was send
, but Futurae was not able to send the SMS, because the SMS sender name is not configured.
Lookup Users
GET /srv/auth/v1/users
Lookup up a user based on various filters [Currently only lookup by username is supported.]
Query Parameters
Example request query params:
username=someuser%40domain.com
usernamestring required |
The username of the user to lookup. |
Response 200
Example response:
200 OK
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"username": "someone@domain.com",
"status": "enabled"
}
Request was successful.
Fields | |
---|---|
user_idstring
|
The permanent, unique identifier of the user in Futurae. |
usernamestring
|
The username of this user. |
statusstring
|
The user's status. It will be one of the values described in User Status. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the specified username
does not exist.
Get User Information
Example request:
GET /srv/auth/v1/users/7adc0abe-4820-4ba8-b8ea-a3eaa2860eb
GET /srv/auth/v1/users/{id}
Get information about the status and the enrolled devices of the user with Futurae ID id
.
Response 200
Example response:
200 OK
{
"username": "someone@domain.com",
"display_name": "someone",
"status": "enabled",
"allowed_factors" : [
"approve",
"mobile_totp",
"passcode"
],
"devices": [
{
"device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd",
"display_name": "My iphone X",
"capabilities": [
"approve",
"qr_code",
"mobile_totp",
"qr_code"
],
"type": "ios",
"version": "1.0.1",
"version_supported": true,
"account_recovery_flow_binding_enabled": true,
"device_integrity": "jailbroken",
"device_integrity_updated_at": 1715851709,
"enrolled_at": 1688814949
}
]
}
Request was successful.
Fields | |
---|---|
usernamestring
|
The username of this user. This serves as an alternative identifier which can be specified by your application, or generated randomly by Futurae. |
display_namestring
|
The display name of the user, which is displayed on the user's Futurae mobile app. An empty string means no display name is currently set. |
statusstring
|
The user's status. It will be one of the values described in User Status. |
allowed_factors[string] optional |
A list of the authentication factors that are permitted to be used for this user. One or more of the factors described in Allowed Factors will be contained in the list. |
devices[object] optional |
A list of the user’s devices and their capabilities. Refer to the Device resource for a description of the format of each device in this array. |
enrolled_atnumber optional |
The time when this device was enrolled to a user, represented as a Unix timestamp. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
The specified user id
does not exist.
Modify User
POST /srv/auth/v1/users/{id}
Modify attributes of the user with Futurae ID id
.
Body Parameters
Example request body params:
{
"allowed_factors": ["mobile_totp", "approve", "passcode"],
"status": "enabled",
"username": "newusername@domain.com",
"display_name": "Cooler display name",
"max_attempts": 15
}
allowed_factors[string] optional |
A list containing the Futurae authentication technologies which the user is eligible to use. By default, upon user creation the user is eligible for all possible factors, depending on the capabilities of his devices. This default behavior can change by using this endpoint and specifying a more restricted set of allowed factors. See Allowed Factors for a description of the available factors. |
statusstring optional |
Manipulate the user status.Set to one of the following values:enabled — Setting to enabled will remove the bypass status, meaning that the user will have to authenticate using Futurae authentication. It will also reset the user to be able to authenticate again, in case he was locked out. Note, however, that if the user has no enrolled devices, his status will immediately become disabled , as he still needs to enroll a new device in order to be able to use Futurae authentication.bypass — Setting to bypass will allow the user to completely bypass Futurae authentication from now on. It will also reset the user to be able to authenticate again, in case he was locked out.locked_out — Setting to locked_out will temporarily disable the ability of the user to authenticate with Futurae. His status needs to be reset (i.e., set to enabled or bypass ) before he can authenticate again.disabled — If set to disabled , then any enrolled devices for that user will automatically be unenrolled, and the user will have to enroll a device again in order to authenticate using Futurae authentication. Moreover, similar to setting to enabled , it will reset the bypass or locked_out status (i.e., the user will no more be in bypass mode or locked out). |
usernamestring optional |
Set a new username for this user. The username must be unique. If it is not, the call will result in a 400 error. Note that in order to avoid any issues, make sure that this change is reflected by a change of the username in your application, too.See the input restrictions that apply. |
display_namestring optional |
Set a new display name for this user (displayed in the user's Futurae mobile app). As an example, it could be the user's email address. See the input restrictions that apply. |
max_attemptsnumber optional |
Set the maximum number of consecutive failed authentication attempts allowed for the user before he gets locked out. A value of 15 (which is the default value) means that the user will be locked out on the 16th consecutive failed attempt. The default value can be configured per each Futurae Service in Futurae Admin (newly created users will have the specified default value). Minimum: 5 Maximum: 40
|
Response 200
Example response:
200 OK
{
"status": "enabled",
"username": "newusername@domain.com",
"display_name": "Cooler display name"
}
Request was successful. Depending on the supplied request body parameters the response body will contain the values of all the updated user attributes, or it will be empty if no attribute was updated.
Fields | |
---|---|
allowed_factors[string] optional |
The list of the user's allowed factors, if updated. |
statusstring optional |
The user status, if updated. It will be one of the values described in User Status. |
usernamestring optional |
The username, if updated. |
display_namestring optional |
The display name, if updated. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid parameters, or the specified user id
does not exist, or the specified username
already exists.
Unenroll User Device
POST /srv/auth/v1/user/unenroll
Unenroll (deactivate) a device of a user. If the specified device is the only enrolled device for the user, then Futurae authentication will automatically be disabled for this user (his User Status will change to disabled
). The user will have to enroll a device again in order to be able to use Futurae authentication.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"device_id": "5bde7d1f-206b-4857-877d-f314912b83f0"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
device_idstring required |
The ID of the device that will be unenrolled. |
Response 200
Example response:
200 OK
{
"result": "success"
}
Request was successful.
Fields | |
---|---|
resultstring
|
Describes the result of the device unenrollment. It can have one of the following values:success — The specified device was successfully unenrolled.success_2fa_disabled — The specified device was successfully unenrolled. Moreover, this was the only enrolled device for the user, therefore Futurae authentication was automatically disabled for that user (his User Status is now changed to disabled ). |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the particular user_id
and device_id
combination does not exist, or the specified device_id
is already unenrolled.
Modify User Device
POST /srv/auth/v1/user/devices/{id}
Modify a user device with ID id
.
Body Parameters
Example request body params:
{
"display_name": "My Android phone",
"account_recovery_flow_binding_enabled": true
}
display_namestring optional |
Sets a custom display name for that particular device. Useful for when a user has multiple devices enrolled with his account. It can serve as a (typically user-chosen) mnemonic name to help the user choose which device he wishes to use for Futurae authentication. By default, for Futurae mobile app devices the display name is the device model. For SMS devices, the default display name is the phone number. The following restrictions apply to display_name (maximum length: 100 characters): Can be a string with spaces and with category L letters, numbers ([0-9]), or the characters - + / . ( ) . |
account_recovery_flow_binding_enabledboolean optional |
Set this field to true to enable Trusted Session Binding for account recovery. |
Response 200
Example response:
200 OK
{
}
Request was successful.
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the specified device id
does not exist.
Create Trusted Session Binding Token
POST /srv/auth/v1/binding_token
This endpoint creates a unique token for a given scope within the Futurae service to be used for Trusted Session Binding authentication purposes. This token should be used only once.
Body Parameters
Example request body params:
{
"version": 1,
"valid_secs": 120,
"flow": "enrollment",
"activation_code": "NUhiSXk4eF9LRVE3SXdFZDZvRmVUeFd4Qy1BWGtPUlJZX1JnM0ctZm1EQWk6N2E3ZjUyMDktZWUwOS00ZDU0LThlYzAtY2Y2MTAyYjVmNGI2OmFwaS10ZXN0LmZ1dHVyYWUuY29t"
}
versionnumber required |
Current supported version is 1 . |
valid_secsnumber optional |
Time, in seconds, for which the token will remain valid. Minimum: 1 Maximum: 600 (10 mins)Default: 120 (2 mins) |
flowstring required |
The flow, for which the Trusted Session Binding token will be created. Current supported values: enrollment and account_recovery . |
activation_codestring optional |
The activation code of the enrollment session, for which the Trusted Session Binding token will be created. This field is mandatory when the flow value is enrollment . |
device_ids[string] optional |
The list of device IDs, for which the Trusted Session Binding token for Account Recovery will be created. The device IDs must be from a single app installation. This field is mandatory when the flow value is account_recovery . |
Response 201
Example response:
201 Created
{
"binding_token": "eyJhbGciOiJBMjU2S1ciLCJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwidHlwIjoiSldUIn0.VR4n8wQPUAlb_TEUukPAB-67bd6m9vZnLQy1ub5UW96Lr4zmF4frIw.7AJiJS0f9vjm3hxi.kCrqENiICYMZUNgo1eoDLzI6eejQxJO14Z3O8cdiwYpKRzkBO8NxRzR7nzZgwDDjGQKlkr0LUp_fKA3c81Z1FMVm23ktwLsDtya5njv8FOaSVTC3eu4nKhA2oEV6gxWVZRi8VUG1w5rwJPoXiBWlPgC8lnviAOlv8gdvRgg6XYYfKBIvqaFO3pYaZmdvpuFWqzAN8yfRXABmWX_PNFeJTEqcn4xkIU4HtQTEml6mrDPUAwCmefXt1-GRTKgr7OD4qRqeRD52Gn5zcMwnK_UGLzsVSKVEFJcNSSG1s8qSOsB9FAUSV0_mWLllp0D6klC_0OBMW7gS50gfblRvBZu6iZRxR7bDdhaCkyqvpjI8vpUZ6kCJHDg6ZG5qusdzJO56CqUt6fHINmVmzAeMCtnmTp-8Zb8egv2EcbNTrPvj7eJG7PzZX5PxQ-jqXavSST2WFiw99rq9ZQByegatr2DRB6rjpgTSXghD8QBwqtNs8mxTuQuwIOYvHHcdGvDAoqdPCSrwQzjJx_dbEY2W8yRWC2MaIeFg_rZlhxmTTGISUVXBNS1PGEniM8wRcfXa-iMfg9gkCvO4rL5KfkpHXhp02x9S55_TLkPWQeGmkPwsIxOHHmN8hXKDLi96V8oUxw2XX6Uj_e3k9MomiwukCqYOw2ljimDWtWZJRqYaNmEde5dm5pPi1IRz-HkIIGo715wJSZKvJ7hd28Bqt3QV.hGAPWGKmL0trP_Rgd2gsBQ"
}
Request was successful.
Fields | |
---|---|
binding_token[string]
|
The newly created Trusted Session Binding token, which enables Trusted Session Binding for the requested session and flow. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters. For example, the specified activation_code
is empty or already enrolled or version
, flow
and/or valid_secs
is not supported.
Authentication
Endpoints related to user authentication procedures.
Query Authentication Options
POST /srv/auth/v1/user/preauth
Check if the user should perform Futurae authentication and if so, return the available authentication options for this user.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"trusted_device_token": "ExANyywJKiI7oNCo YE9FnjVbJZW3QlPY2LFxDBx8CXU="
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
trusted_device_tokenstring optional |
If the supplied token is valid, return an “allow” response, meaning that the user does not have to perform Futurae authentication as the attempt originates from a trusted device. |
Response 200
Example responses:
200 OK
{
"result": "auth",
"allowed_factors" : [
"approve",
"mobile_totp",
"passcode"
],
"devices": [
{
"device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd",
"display_name": "My iphone X",
"capabilities": [
"approve",
"qr_code",
"mobile_totp",
"qr_code"
],
"type": "ios",
"version": "1.0.1",
"version_supported": true,
"device_integrity": "jailbroken",
"device_integrity_updated_at": 1715851709,
"enrolled_at": 1688814949
}
],
"recommended_factor": "approve"
}
200 OK
{
"result": "deny",
"user_status": "disabled"
}
200 OK
{
"result": "allow",
"user_status": "bypass"
}
Request was successful.
Fields | |
---|---|
resultstring
|
It will be one of the following values:auth — The user is eligible for Futurae authentication. Use Authenticate User to proceed. Alternatively, for performing transaction authentication use Authenticate Transaction.allow — The user is configured to bypass Futurae authentication, or is authenticating from a trusted device (valid trusted_device_token was supplied). In either case, the user should be directly granted access. Moreover, in the first case, the optional user_status field will be present in the response and will have the value bypass .deny — The user is not permitted to authenticate at this time and should be denied access. This means that the user is either locked out, or the user has no enrolled devices and thus Futurae authentication is disabled (the User Status is disabled ). In this case, the response will also contain the optional user_status field in order to help you identify the exact reason. unknown — The specified user_id or username is not recognized by Futurae, and as such, Futurae authentication does not apply. For new users, or in case the supplied user_id is a remnant of a previously deleted user in Futurae, use Enroll Users and Devices, in order to enroll this user for Futurae authentication. |
allowed_factors[string] optional |
A list of the authentication factors that are permitted to be used for this user. One or more of the factors described in Allowed Factors will be contained in the list. |
devices[object] optional |
A list of the user’s devices and their capabilities. Refer to the Device resource for a description of the format of each device in this array. |
recommended_factorstring optional |
The factor to use for authentication as recommended by Futurae, and based on the capabilities of the user's devices. |
user_statusstring optional |
The user's status. This field will be present if the user's status is locked_out , disabled or bypass (see the values descriptions in User Status).
|
enrolled_atnumber optional |
The time when this device was enrolled to a user, represented as a Unix timestamp. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing params. Most likely, you did not supply neither a user_id
nor a username
, or you supplied both at the same time. You should supply only one of the two. Also, make sure that all of your params are string
values.
Authenticate User
POST /srv/auth/v1/user/auth
Perform Futurae authentication for a particular user using one of the available Futurae authentication technologies (factors). The input parameters as well as the response of this endpoint depend on the chosen factor.
Authenticate with One-Touch
POST /srv/auth/v1/user/auth
Send a push notification to the user's mobile device, which will prompt the user to review and approve or reject the authentication attempt. This endpoint will return immediately providing a session_id
, which your application can use in order to query the status and eventually retrieve the result of this particular authentication session using Query Authentication Status. Alternatively, you can use callbacks in order to be notified about the authentication result as described further below.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "approve",
"device_id": "auto",
"type": "Login",
"extra_info": [{"key": "location", "value": "near Zurich"}, {"key": "IP address", "value": "129.132.211.73"}, {"key": "browser", "value": "Google Chrome"}],
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
"adaptive_session_token": "c29tZXJhbmRvbXN0cmluZw",
"session_timeout": 90
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be approve . |
device_idstring required |
The ID of the device to use. The device must support the approve capability (see Device Capabilities). You can also specify auto in which case the most recently enrolled of the user’s devices with the approve capability will be used.Finally, you can specify all in which case all the enrolled user’s devices with the approve capability are notified with a push notification, and any of them can be used to approve or reject the particular authentication attempt. |
offline_fallbackboolean optional |
Set this param to true to combine One-Touch with an offline QR code session which will serve as fallback.Default: false
|
typestring optional |
This string is displayed in the Futurae mobile app on the approval details screen. If supplied, it must not be an empty string. Default: Login
|
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The Futurae app will display this information to the user in the approval details screen, in the order specified in the array.Maximum number of key -value objects accepted for the extra_info array: 20 Maximum length in bytes allowed for each JSON key field: 100 Maximum length in bytes allowed for each JSON value field: 2000 Maximum length in bytes allowed for all JSON key -value pairs together: 2000 When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg , device_id , trusted_device_token and user_presence_verification . The user_presence_verification field will only be present if the particular feature is enabled and result is allow . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
mobile_auth_redirect_uristring optional |
When the authentication attempt takes place on a device on which the Futurae mobile app is installed and enrolled (mobile only), this is the redirect URI which the Futurae iOS app will call once Futurae authentication is completed. Refer to the mobile only guide for more information on how to use this parameter. |
set_trustedboolean optional |
When set to true , then if the authentication is successful (i.e., result is allow ), also return a trusted device token which can be used in the future to mark the device from which the authentication attempt took place as trusted. This can later be passed to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from this device.Default: false
|
trusted_daysnumber optional |
A number that indicates the number of days for which the trusted device token will be valid, before it expires. A value of 0 and for any value exceeding 30 , means that the token will be valid for the default value number of days. Applicable only when set_trusted is true .Default: 30
|
adaptive_session_token[string] optional
|
The adaptive session token is a backend generated token which uniquely identifies the adaptive session. It is generated when the adaptive session is initialized, through the initialize of the adaptive session. Applicable only when the User Risk Radar feature is enabled. |
session_timeoutnumber optional |
A number that indicates the session timeout value in seconds. Minimum: 30 Maximum: 120 Default: 60 (Configurable by the Update Service Information endpoint) |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}
Request was successful.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
mobile_auth_uristring
|
A URI which can be used for performing authentication when the authentication attempt takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"multi_numbered_challenge_value": 52
}
Successful request when the Multi-Numbered Challenge feature is enabled.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
mobile_auth_uristring
|
A URI which can be used for performing authentication when the authentication attempt takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
multi_numbered_challenge_valueint
|
A unique value generated as part of a multi-numbered challenge. |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"fallback_session_id": "7818828e-1517-4b8c-934e-bc233d84a293",
"fallback_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"fallback_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?auth=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}
Successful request with offline_fallback
set to true
.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
mobile_auth_uristring
|
A URI which can be used for performing authentication when the authentication attempt takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
fallback_session_idstring
|
A session ID that identifies the offline QR code fallback authentication session. It can be used to receive real-time updates regarding the status of the fallback authentication session using Query Authentication Status. Moreover, it can be used to verify the validity of the user-supplied code using Validate Offline QR Code. |
fallback_qrcode_urlstring
|
The URL from which the QR code (encoded as a PNG image) of this particular fallback authentication session can be retrieved. The URL will be valid for as long as the fallback authentication attempt hasn't timed out, which is approximately 2 minutes. Note that the URL is directly accessible (i.e., no Authorization header needed). |
fallback_qrcode_data_uristring
|
The PNG image of the QR code of this particular fallback authentication in data URI scheme. This is the same QR code image that can be retrieved via fallback_qrcode_url .
|
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Authenticate with Mobile Auth
POST /srv/auth/v1/user/auth
A URI-based authentication which can be used to authenticate when the attempt takes place on a device on which the Futurae, white-label or SDK based mobile apps are installed and enrolled (mobile only). Refer to the mobile only guide for more information.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "mobile_auth",
"device_id": "auto",
"type": "Login",
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
"adaptive_session_token": "c29tZXJhbmRvbXN0cmluZw",
"session_timeout": 90
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be mobile_auth . |
device_idstring required |
The ID of the device to use. The device must support the mobile_auth capability (see Device Capabilities). You can also specify auto in which case the most recently enrolled of the user’s devices with the mobile_auth capability will be used.Finally, you can specify all in which case all the enrolled user’s devices with the mobile_auth capability can be used to approve or reject the particular authentication attempt. |
typestring optional |
This string is displayed in the Futurae mobile app on the approval details screen. If supplied, it must not be an empty string. Default: Login
|
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The Futurae app will display this information to the user in the approval details screen, in the order specified in the array.Maximum number of key -value objects accepted for the extra_info array: 20 Maximum length in bytes allowed for each JSON key field: 100 Maximum length in bytes allowed for each JSON value field: 2000 Maximum length in bytes allowed for all JSON key -value pairs together: 2000 When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg , device_id , trusted_device_token and user_presence_verification . The user_presence_verification field will only be present if the particular feature is enabled and result is allow . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
mobile_auth_redirect_uristring optional |
When the authentication attempt takes place on a device on which the Futurae mobile app is installed and enrolled (mobile only), this is the redirect URI which the Futurae iOS app will call once Futurae authentication is completed. Refer to the mobile only guide for more information on how to use this parameter. |
set_trustedboolean optional |
When set to true , then if the authentication is successful (i.e., result is allow ), also return a trusted device token which can be used in the future to mark the device from which the authentication attempt took place as trusted. This can later be passed to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from this device.Default: false
|
trusted_daysnumber optional |
A number that indicates the number of days for which the trusted device token will be valid, before it expires. A value of 0 and for any value exceeding 30 , means that the token will be valid for the default value number of days. Applicable only when set_trusted is true .Default: 30
|
adaptive_session_token[string] optional
|
The adaptive session token is a backend generated token which uniquely identifies the adaptive session. It is generated when the adaptive session is initialized, through the initialize of the adaptive session. Applicable only when the User Risk Radar feature is enabled. |
session_timeoutnumber optional |
A number that indicates the session timeout value in seconds. Minimum: 30 Maximum: 120 Default: 60 (Configurable by the Update Service Information endpoint) |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}
Request was successful.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
mobile_auth_uristring
|
A URI which can be used for performing authentication when the authentication attempt takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Authenticate with Synchronous Auth
POST /srv/auth/v1/user/auth
A synchronous OTP based authentication which can be used to authenticate when the attempt takes place on a device with an enrolled SDK based mobile app (mobile only guide).
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "sync",
"device_id": "71189254-171e-4161-92a0-fdcbad6a260a",
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJob3RwIjoiMTgyNzMxIiwic3luY19jb3VudGVyIjoxLCJkZXZpY2VfaWQiOiI2MWUwYmVmMS03ODI2LTkyMzctZDM2Mi1hM2VhYTI4Njk5MTkifQ.esR3PfNs8HfM64EuapsU0eGiSyD_GOwN7LyNmvcQy7A"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be sync . |
device_idstring required |
The ID of the device to use for this particular authentication attempt. The device must support the sync capability (see Device Capabilities). |
tokenstring required |
A JSON Web Token (JWT) generated and sent by the mobile app requesting the authentication. |
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "allow",
"status_msg": "Authentication succeeded."
}
Request was successful.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Authenticate with FIDO2/WebAuthn
POST /srv/auth/v1/user/auth
Authenticate the user with FIDO2/WebAuthn, using one of the user's enrolled FIDO Devices.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "fido",
"device_id": "auto",
"user_verification": "required",
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
"session_timeout": 90
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be fido . |
device_idstring required |
The ID of the device to use. The device must support the fido capability (see Device Capabilities). You can also specify auto in which case the most recently enrolled of the user’s devices with the fido capability will be used.Finally, you can specify all in which case any of the enrolled user’s devices with the fido capability can be used for this particular authentication attempt. |
user_verificationstring optional |
The Relying Party's requirements regarding user verification for this particular authentication attempt. It can be required , preferred , or discouraged . Default: The corresponding attribute value of the Relying Party's WebAuthn RP Configuration. |
transport[string] optional |
The authenticator transports that can be used for this particular authentication attempt. Default: ["usb", "nfc", "ble", "internal"] , i.e., all possible transports. |
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg , device_id and trusted_device_token . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
set_trustedboolean optional |
When set to true , then if the authentication is successful (i.e., result is allow ), also return a trusted device token which can be used in the future to mark the device from which the authentication attempt took place as trusted. This can later be passed to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from this device.Default: false . |
trusted_daysnumber optional |
A number that indicates the number of days for which the trusted device token will be valid, before it expires. A value of 0 and for any value exceeding 30 , means that the token will be valid for the default value number of days. Applicable only when set_trusted is true .Default: 30
|
session_timeoutnumber optional |
A number that indicates the session timeout value in seconds. Minimum: 30 Maximum: 120 Default: 60 (Configurable by the Update Service Information endpoint) |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"session_token": "qQNlDg7mN2kdjlvk5HsFkLWzdJkHFPvqiTsAg5TE"
}
Request was successful.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
session_tokenstring
|
This token has to be passed as argument to WebAuthnJS SDK's auth() method, in order to start the authentication process on the client side. |
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
Operation is forbidden. One of the following reasons apply:
- The Service doesn't have an associated WebAuthn RP Configuration. Call Admin API's Create RP Configuration to create it.
- The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Authenticate with Passcode
POST /srv/auth/v1/user/auth
Perform authentication based on a user-supplied passcode.
Additionally, note that you can attempt to invoke this endpoint and perform passcode authentication using a Backup Code or an One-Time Code, even if Query Authentication Options returns deny
. This can be useful for recovery purposes and for authenticating users with no enrolled devices whose User Status is disabled
.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "passcode",
"passcode": "328905",
"set_trusted": true,
"trusted_days": 1,
"adaptive_session_token": "c29tZXJhbmRvbXN0cmluZw"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be passcode . |
passcodestring required |
The passcode submitted by the user. It does not matter if the code contains spaces, as Futurae will ignore them when validating the code. |
set_trustedboolean optional |
When set to true , then if the authentication is successful (i.e., result is allow ), also return a trusted device token which can be used in the future to mark the device from which the authentication attempt took place as trusted. This can later be passed to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from this device.Default: false
|
trusted_daysnumber optional |
A number that indicates the number of days for which the trusted device token will be valid, before it expires. A value of 0 and for any value exceeding 30 , means that the token will be valid for the default value number of days. Applicable only when set_trusted is true .Default: 30
|
adaptive_session_token[string] optional
|
The adaptive session token is a backend generated token which uniquely identifies the adaptive session. It is generated when the adaptive session is initialized, through the initialize of the adaptive session. It is only supported for TOTP hardware token and mobile TOTP. Applicable only when the User Risk Radar feature is enabled. |
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "allow",
"status_msg": "Authentication succeeded.",
"passcode_type": "mobile_totp",
"device_id": "d0b4746b-1f02-409d-892c-abae473244b7",
"trusted_device_token": "ExANyywJKiI7oNCoYE9FnjVbJZW3QlPY2LFxDBx8CXU="
}
Request was successful. The response contains the authentication result.
Fields | |
---|---|
resultstring
|
Either allow or deny . See Authentication Result for details. |
statusstring
|
String detailing the progress or outcome of the authentication attempt. If the authentication attempt was denied, it may identify a reason, and depending on the scenario your application should retry the process. It will be one of the values described in Authentication Status. |
status_msgstring
|
A string describing the status or result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user, although it is advisable that you customize the output to the user, to better tailor the wording to the style of your website. |
passcode_typestring
|
A string describing the type of passcode which was used to complete this authentication attempt. It will have one the following values: mobile_totp (TOTP generated by the Futurae mobile app, white-label app, or mobile SDK), hwtoken_totp (generated by a TOTP hardware token), sms (generated via Authenticate with SMS), one_time_code (generated via One-Time Codes or backup_code (generated via Backup Codes. |
device_idstring optional |
When passcode_type is mobile_totp or hwtoken_totp , this field contains the ID of the user's device which matched the passcode submitted by the user. In all other cases, this field is not part of the response. |
trusted_device_tokenstring optional |
This field will be present if the authentication was successful (i.e., result was allow ) and Authenticate User had been called with the set_trusted parameter set to true for this particular session.In this case, this serves as a secure token (cookie) that can be used to mark the device from which the authentication attempt took place as trusted. The token can later be supplied to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from a trusted device. |
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters. For example, the specified user_id
does not exist.
Authenticate with QR Code
POST /srv/auth/v1/user/auth
Show a QR code on the screen which the user has to scan with the Futurae mobile app and approve or reject the authentication attempt.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "qr_code",
"extra_info": [{"key": "location", "value": "near Zurich"}, {"key": "IP address", "value": "129.132.211.73"}, {"key": "browser", "value": "Google Chrome"}],
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
"adaptive_session_token": "c29tZXJhbmRvbXN0cmluZw",
"session_timeout": 90
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be qr_code . |
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The Futurae app will display this information to the user in the approval details screen, in the order specified in the array.Maximum number of key -value objects accepted for the extra_info array: 20 Maximum length in bytes allowed for each JSON key field: 100 Maximum length in bytes allowed for each JSON value field: 2000 Maximum length in bytes allowed for all JSON key -value pairs together: 2000 When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg , device_id , trusted_device_token and user_presence_verification . The user_presence_verification field will only be present if the particular feature is enabled and result is allow . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
mobile_auth_redirect_uristring optional |
When the authentication attempt takes place on a device on which the Futurae mobile app is installed and enrolled (mobile only), this is the redirect URI which the Futurae iOS app will call once Futurae authentication is completed. Refer to the mobile only guide for more information on how to use this parameter. |
set_trustedboolean optional |
When set to true , then if the authentication is successful (i.e., result is allow ), also return a trusted device token which can be used in the future to mark the device from which the authentication attempt took place as trusted. This can later be passed to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from this device.Default: false
|
trusted_daysnumber optional |
A number that indicates the number of days for which the trusted device token will be valid, before it expires. A value of 0 and for any value exceeding 30 , means that the token will be valid for the default value number of days. Applicable only when set_trusted is true .Default: 30
|
adaptive_session_token[string] optional
|
The adaptive session token is a backend generated token which uniquely identifies the adaptive session. It is generated when the adaptive session is initialized, through the initialize of the adaptive session. Applicable only when the User Risk Radar feature is enabled. |
session_timeoutnumber optional |
A number that indicates the session timeout value in seconds. Minimum: 30 Maximum: 120 Default: 60 (Configurable by the Update Service Information endpoint) |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?auth=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}
Successful request.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
qrcode_urlstring
|
The URL from which the QR code (encoded as a PNG image) of this particular authentication session can be retrieved. The URL will be valid for as long as the authentication attempt hasn't timed out, which is approximately 1 minute. Note that the URL is directly accessible (i.e., no Authorization header needed). |
qrcode_data_uristring
|
The PNG image of the QR code of this particular authentication in data URI scheme. This is the same QR code image that can be retrieved via qrcode_url .
|
mobile_auth_uristring
|
A URI which can be used for performing authentication when the authentication attempt takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - There was no available device found that supports the capability needed for the chosen
factor
. In this case, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Authenticate with Offline QR Code
POST /srv/auth/v1/user/auth
Show a QR code on the screen which the user has to scan using the app or hardware token, subsequently approve or reject the authentication attempt in the app and, if the user approves, enter the app/token-generated code in your application. Finally, your application will have to verify the validity of the supplied code using Validate Offline QR Code.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "qr_code",
"offline": true,
"extra_info": [{"key": "location", "value": "near Zurich"}, {"key": "IP address", "value": "129.132.211.73"}, {"key": "browser", "value": "Google Chrome"}],
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
"adaptive_session_token": "c29tZXJhbmRvbXN0cmluZw"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be qr_code . |
offlineboolean required |
Must be true in order to perform offline QR code authentication. If not supplied or if set to false , Authenticate with QR Code (i.e., the online version) is executed instead. |
device_idstring optional |
The ID of the device to use for this particular authentication attempt. The device must support the qr_code capability (see Device Capabilities). This field is:
|
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The Futurae app will display this information to the user in the approval details screen, in the order specified in the array.Maximum number of key -value objects accepted for the extra_info array: 20 Maximum length in bytes allowed for each JSON key field: 100 Maximum length in bytes allowed for each JSON value field: 2000 Maximum length in bytes allowed for all JSON key -value pairs together: 2000 When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg , device_id and trusted_device_token . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
set_trustedboolean optional |
When set to true , then if the authentication is successful (i.e., result is allow ), also return a trusted device token which can be used in the future to mark the device from which the authentication attempt took place as trusted. This can later be passed to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from this device.Default: false
|
trusted_daysnumber optional |
A number that indicates the number of days for which the trusted device token will be valid, before it expires. A value of 0 and for any value exceeding 30 , means that the token will be valid for the default value number of days. Applicable only when set_trusted is true .Default: 30
|
adaptive_session_token[string] optional
|
The adaptive session token is a backend generated token which uniquely identifies the adaptive session. It is generated when the adaptive session is initialized, through the initialize of the adaptive session. Applicable only when the User Risk Radar feature is enabled. |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?auth=40de80c1-0yuNkJ20pQoNKuaRvGQ1rQPtBPAUyA3bQ0Q4kzpGrcmz0"
}
Successful request.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. Moreover, it can be used to verify the validity of the user-supplied code using Validate Offline QR Code. |
qrcode_urlstring
|
The URL from which the QR code (encoded as a PNG image) of this particular authentication session can be retrieved. The URL will be valid for as long as the authentication attempt hasn't timed out, which is approximately 1 minute. Note that the URL is directly accessible (i.e., no Authorization header needed). |
qrcode_data_uristring
|
The PNG image of the QR code of this particular authentication in data URI scheme. This is the same QR code image that can be retrieved via qrcode_url .
|
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. One particular case of invalid parameters worth mentioning is when the specifieddevice_id
is a hardware token, and theextra_info
input parameter contains characters which cannot be converted to ISO 8859-15 (the character set supported by the hardware tokens). - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Validate Offline QR Code
POST /srv/auth/v1/user/auth
Use this endpoint to validate the code supplied by the user as part of Authenticate with Offline QR Code, Authenticate Transaction with Offline QR Code, Authenticate with One-Touch with offline_fallback
set to true
, and Authenticate Transaction with One-Touch with offline_fallback
set to true
.
Depending on the supplied parameters, different responses can be expected (described further below). Meanwhile, at any point during the authentication session, you can invoke Query Authentication Status to check the status and get the result of this particular session.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "qr_code",
"passcode": "123456",
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"adaptive_session_token": "c29tZXJhbmRvbXN0cmluZw"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be qr_code . |
passcodestring required |
The code supplied by the user. |
session_idstring required |
The session ID of the authentication attempt, or the fallback authentication attempt. |
adaptive_session_token[string] optional
|
The adaptive session token is a backend generated token which uniquely identifies the adaptive session. It is generated when the adaptive session is initialized, through the initialize of the adaptive session. Applicable only when the User Risk Radar feature is enabled. |
Response 200
Example response:
200 OK
{
"result": "waiting",
"status": "qr_code_retry",
"status_msg": "QR code offline passcode verification failed; retry."
}
The supplied code was not the correct one for this particular authentication session. The user can retry (maximum three attempts).
Fields | |
---|---|
resultstring
|
It will be waiting . |
statusstring
|
It will be qr_code_retry . |
status_msgstring
|
A message describing the fact that the code verification failed and that a retry is possible. |
Response 200
Example response:
200 OK
{
"result": "deny",
"status": "deny",
"status_msg": "Authentication failed."
}
The user has a maximum of three attempts per authentication session to supply the correct code. This attempt was the third failed one, so the authentication session is completed unsuccessfully and the user should be denied access. Depending on your application logic, the user might be able to start over (initiate a new authentication attempt).
Fields | |
---|---|
resultstring
|
It will be deny . |
statusstring
|
It will be deny . |
status_msgstring
|
A message describing that authentication failed. |
Response 200
Example response:
200 OK
{
"device_id": "bb8e8568-e5f7-4524-b250-6d0873fe9eee",
"result": "allow",
"status": "allow",
"status_msg": "Authentication succeeded."
}
The supplied code is correct (this was one of the three allowed attempts). The authentication session is completed successfully and the user should be allowed access.
Fields | |
---|---|
device_idstring
|
The ID of the authenticator device. |
resultstring
|
It will be allow . |
statusstring
|
It will be allow . |
status_msgstring
|
A message describing that authentication succeeded. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
One of the following holds:
- The session has already timed out (typically after one minute)
- The session is unknown
- The session has been already finalized. (In other words, you already submitted a code that was correct, or you already have had three failed attempts for this particular session.)
- Bad or missing request parameters.
Authenticate with Usernameless QR Code
POST /srv/auth/v1/user/auth
Generate a usernameless QR code that is not bound to any specific user. The generated QR code can be scanned by any user of the Service, who will then be prompted to approve or deny the associated session.
Body Parameters
Example request body params:
{
"factor": "usernameless_qr_code"
}
factorstring required |
Must be usernameless_qr_code . |
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The mobile app can display this information to the user in the approval details screen, in the order specified in the array.When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg and trusted_device_token . The session ID identifies the particular authentication session (see response below). See Query Authentication Status for the description of the rest of the fields.
|
typestring optional |
This string can be displayed in mobile app on the approval details screen. If supplied, it must not be an empty string. Default: Login
|
session_timeoutnumber optional |
A number that indicates the session timeout value in seconds. If omitted the value will not be updated. Minimum: 30 Maximum: 120 Default: 60 (Configurable by the Update Service Information endpoint) |
Response 200
Example response:
200 OK
{
"qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?auth=B3zBuxnqcrcwW5q9zQGYwa_Po6CCYKFbON9IX6XqLoyB",
"session_id": "ef3819ca-9310-41b8-9ce8-2a0a102f62fa"
}
Successful request, usernameless QR code was generated.
Fields | |
---|---|
qrcode_data_uristring
|
The PNG image of the QR code of this particular authentication in data URI scheme. This is the same QR code image that can be retrieved via qrcode_url .
|
qrcode_urlstring
|
The URL from which the QR code (encoded as a PNG image) of this particular authentication session can be retrieved. The URL will be valid for as long as the authentication attempt hasn't timed out, which is approximately 1 minute. Note that the URL is directly accessible (i.e., no Authorization header needed). |
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- The
session_timeout
value does not fall into the allowed limits. - The
status_callback_url
is not a proper formatted URL.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
Request failed because a user_id
was provided in the request payload which is not allowed for usernameless_qr_code
factor.
Authenticate with SMS
POST /srv/auth/v1/user/auth
Send an SMS one-time code to the user.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "sms",
"device_id": "auto",
"set_trusted": true,
"trusted_days": 1
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be sms . |
device_idstring required |
The ID of the device to send the SMS to. The device must support the sms capability, i.e., it must be have an associated phone number (see Device Capabilities). Alternatively, you can specify auto , in which case the most recently enrolled of the user’s devices with the sms capability will be used. |
sms_textstring optional |
The default text contained in the SMS is:Your login code is , followed by a space character and the passcode. If you want to change the default text, you can supply this parameter with the text of your choice. If the placeholder $OTP is present on the message it is replaced by the passcode and it won't be included at the end of the message.Maximum length: If characters outside the GSM-7 character set are used, the maximum length is 60 characters. Otherwise, the maximum length is 153 characters, except if the message contains the characters ^{}[]~|€ which are counted as 2 characters each. |
valid_secsnumber optional |
Time, in seconds, for which the SMS one-time code will remain valid. Minimum: 60 (1 minute)Maximum: 1800 (30 minutes)Default: 180 (3 minutes) |
set_trustedboolean optional |
When set to true , then if the authentication is successful (i.e., result is allow ), also return a trusted device token which can be used in the future to mark the device from which the authentication attempt took place as trusted. This can later be passed to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from this device.Default: false
|
trusted_daysnumber optional |
A number that indicates the number of days for which the trusted device token will be valid, before it expires. A value of 0 and for any value exceeding 30 , means that the token will be valid for the default value number of days. Applicable only when set_trusted is true .Default: 30
|
Response 200
Example response:
200 OK
{
"result": "deny"
}
Successful request, SMS was sent out to the user's phone.
Fields | |
---|---|
resultstring
|
Always the value deny . This indicates that your application has to use Authenticate with Passcode and submit the passcode supplied by the user, in order to check its validity. Only if the passcode is valid, will the authentication succeed. |
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40303,
"message": "no SMS sender name set"
}
Futurae was not able to send the SMS one-time code, because the SMS service is temporarily unavailable. Your application should retry, or try to use another factor, if available for this user.
Authenticate Transaction
POST /srv/auth/v1/user/auth/transaction
Perform transaction authentication using one of the available Futurae authentication technologies (factors). This endpoint is similar to Authenticate User but tailored for transaction authentication operations. The input parameters as well as the response of this endpoint depend on the chosen factor.
Authenticate Transaction with One-Touch
POST /srv/auth/v1/user/auth/transaction
Send a push notification to the user's mobile device, which will prompt the user to review and approve or reject the specified transaction. This endpoint will return immediately providing a session_id
, which your application can use in order to query the status and eventually retrieve the result of this particular transaction authentication session using Query Authentication Status. Alternatively, you can use callbacks in order to be notified about the transaction authentication result as described further below.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "approve",
"device_id": "auto",
"type": "Transaction",
"extra_info": [{"key": "from", "value": "Savings Account"}, {"key": "to", "value": "Online Store"}, {"key": "IBAN", "value": "CH64 0070 0110 0064 3385 7"}],
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
"session_timeout": 90
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be approve . |
device_idstring required |
The ID of the device to use. The device must support the approve capability (see Device Capabilities). You can also specify auto in which case the most recently enrolled of the user’s devices with the approve capability will be used.Finally, you can specify all in which case all the enrolled user’s devices with the approve capability are notified with a push notification, and any of them can be used to approve or reject the particular transaction authentication attempt. |
offline_fallbackboolean optional |
Set this param to true to combine One-Touch with an offline QR code session which will serve as fallback.Default: false
|
typestring optional |
This string is displayed in the Futurae mobile app on the approval details screen. If supplied, it must not be an empty string. Default: Transaction
|
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The Futurae app will display this information to the user in the approval details screen, in the order specified in the array.Maximum number of key -value objects accepted for the extra_info array: 20 Maximum length in bytes allowed for each JSON key field: 100 Maximum length in bytes allowed for each JSON value field: 2000 Maximum length in bytes allowed for all JSON key -value pairs together: 2000 When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular transaction authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg , device_id and user_presence_verification . The user_presence_verification field will only be present if the particular feature is enabled and result is allow . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
mobile_auth_redirect_uristring optional |
When the transaction takes place on a device on which the Futurae mobile app is installed and enrolled (mobile only), this is the redirect URI which the Futurae iOS app will call once transaction authentication is completed. Refer to the mobile only guide for more information on how to use this parameter. |
session_timeoutnumber optional |
A number that indicates the session timeout value in seconds. Minimum: 30 Maximum: 120 Default: 60 (Configurable by the Update Service Information endpoint) |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}
Request was successful.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created transaction authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
mobile_auth_uristring
|
A URI which can be used for performing transaction authentication when the transaction takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"fallback_session_id": "7818828e-1517-4b8c-934e-bc233d84a293",
"fallback_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"fallback_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?auth=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}
Successful request with offline_fallback
set to true
.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created transaction authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
mobile_auth_uristring
|
A URI which can be used for performing transaction authentication when the transaction takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
fallback_session_idstring
|
A session ID that identifies the offline QR code fallback transaction authentication session. It can be used to receive real-time updates regarding the status of the fallback authentication session using Query Authentication Status. Moreover, it can be used to verify the validity of the user-supplied code using Validate Offline QR Code. |
fallback_qrcode_urlstring
|
The URL from which the QR code (encoded as a PNG image) of this particular fallback transaction authentication session can be retrieved. The URL will be valid for as long as the fallback transaction authentication attempt hasn't timed out, which is approximately 2 minutes. Note that the URL is directly accessible (i.e., no Authorization header needed). |
fallback_qrcode_data_uristring
|
The PNG image of the QR code of this particular fallback transaction authentication in data URI scheme. This is the same QR code image that can be retrieved via fallback_qrcode_url .
|
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Authenticate Transaction with QR Code
POST /srv/auth/v1/user/auth/transaction
Show a QR code on the screen which the user has to scan with the Futurae mobile app, review the specified transaction and approve or reject it.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "qr_code",
"extra_info": [{"key": "from", "value": "Savings Account"}, {"key": "to", "value": "Online Store"}, {"key": "IBAN", "value": "CH64 0070 0110 0064 3385 7"}],
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
"session_timeout": 90
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be qr_code . |
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The Futurae app will display this information to the user in the approval details screen, in the order specified in the array.Maximum number of key -value objects accepted for the extra_info array: 20 Maximum length in bytes allowed for each JSON key field: 100 Maximum length in bytes allowed for each JSON value field: 2000 Maximum length in bytes allowed for all JSON key -value pairs together: 2000 When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular transaction authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg , device_id and user_presence_verification . The user_presence_verification field will only be present if the particular feature is enabled and result is allow . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
mobile_auth_redirect_uristring optional |
When the transaction takes place on a device on which the Futurae mobile app is installed and enrolled (mobile only), this is the redirect URI which the Futurae iOS app will call once transaction authentication is completed. Refer to the mobile only guide for more information on how to use this parameter. |
session_timeoutnumber optional |
A number that indicates the session timeout value in seconds. Minimum: 30 Maximum: 120 Default: 60 (Configurable by the Update Service Information endpoint) |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"qrcode_url": "https://futurae.com/qr?auth=BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}
Successful request.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created transaction authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
qrcode_urlstring
|
The URL from which the QR code (encoded as a PNG image) of this particular transaction authentication session can be retrieved. The URL will be valid for as long as the authentication attempt hasn't timed out, which is approximately 1 minute. Note that the URL is directly accessible (i.e., no Authorization header needed). |
qrcode_data_uristring
|
The PNG image of the QR code of this particular transaction authentication in data URI scheme. This is the same QR code image that can be retrieved via qrcode_url .
|
mobile_auth_uristring
|
A URI which can be used for performing transaction authentication when the transaction takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - There was no available device found that supports the capability needed for the chosen
factor
. In this case, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Authenticate Transaction with Offline QR Code
POST /srv/auth/v1/user/auth/transaction
Show a QR code on the screen which the user has to scan using the app or hardware token, subsequently review the specified transaction and approve or reject it, and, if the user approves, enter the app/token-generated code in your application. Finally, your application will have to verify the validity of the supplied code using Validate Offline QR Code.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "qr_code",
"offline": true,
"device_id": "d0b4746b-1f02-409d-892c-abae473244b7",
"extra_info": [{"key": "from", "value": "Savings Account"}, {"key": "to", "value": "Online Store"}, {"key": "IBAN", "value": "CH64 0070 0110 0064 3385 7"}],
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be qr_code . |
offlineboolean required |
Must be true in order to perform offline QR coden transaction authentication. If not supplied or if set to false , Authenticate Transaction with QR Code (i.e., the online version) is executed instead. |
device_idstring optional |
The ID of the device to use for this particular transaction authentication attempt. The device must support the qr_code capability (see Device Capabilities). This field is:
|
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The Futurae app will display this information to the user in the approval details screen, in the order specified in the array.Maximum number of key -value objects accepted for the extra_info array: 20 Maximum length in bytes allowed for each JSON key field: 100 Maximum length in bytes allowed for each JSON value field: 2000 Maximum length in bytes allowed for all JSON key -value pairs together: 2000 When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular transaction authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg and device_id . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
"qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?auth=40de80c1-0yuNkJ20pQoNKuaRvGQ1rQPtBPAUyA3bQ0Q4kzpGrcmz0"
}
Successful request.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created transaction authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. Moreover, it can be used to verify the validity of the user-supplied code using Validate Offline QR Code. |
qrcode_urlstring
|
The URL from which the QR code (encoded as a PNG image) of this particular transaction authentication session can be retrieved. The URL will be valid for as long as the authentication attempt hasn't timed out, which is approximately 1 minute. Note that the URL is directly accessible (i.e., no Authorization header needed). |
qrcode_data_uristring
|
The PNG image of the QR code of this particular transaction authentication in data URI scheme. This is the same QR code image that can be retrieved via qrcode_url .
|
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "bypass",
"status_msg": "Authentication succeeded."
}
Successful request, however the user is locked out, or can bypass Futurae authentication, or has Futurae authentication disabled (no enrolled devices). In this case the authentication result is immediately returned.
Fields | |
---|---|
resultstring
|
Either allow or deny :allow — Your application should grant access to the user.deny — Your application should deny access to the user. |
statusstring
|
String detailing the reason of the result. One of:bypass — The user can bypass Futurae authentication. The result will be allow .disabled — Futurae authentication is disabled for this user (no enrolled devices). The result will be deny .locked_out — The user is locked out as authentication has failed too many times or his status was programmatically set to this value, and needs to be reset (via Modify User) in order to be able to authenticate again. The result will be deny . |
status_msgstring
|
A string describing the result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. One particular case of invalid parameters worth mentioning is when the specifieddevice_id
is a hardware token, and theextra_info
input parameter contains characters which cannot be converted to ISO 8859-15 (the character set supported by the hardware tokens). - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Authenticate Transaction with Mobile Auth
POST /srv/auth/v1/user/auth/transaction
A URI-based authentication which can be used to approve or reject the specified transaction when the attempt takes place on a device on which the Futurae, white-label or SDK based mobile apps are installed and enrolled (mobile only). Refer to the mobile only guide for more information.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"factor": "mobile_auth",
"device_id": "auto",
"type": "Transaction",
"extra_info": [{"key": "from", "value": "Savings Account"}, {"key": "to", "value": "Online Store"}, {"key": "IBAN", "value": "CH64 0070 0110 0064 3385 7"}],
"status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
"session_timeout": 90
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
factorstring required |
Must be mobile_auth . |
device_idstring required |
The ID of the device to use. The device must support the mobile_auth capability (see Device Capabilities). You can also specify auto in which case the most recently enrolled of the user’s devices with the mobile_auth capability will be used.Finally, you can specify all in which case all the enrolled user’s devices with the mobile_auth capability can be used to approve or reject the particular authentication attempt. |
typestring optional |
This string is displayed in the Futurae mobile app on the approval details screen. If supplied, it must not be an empty string. Default: Login
|
extra_info_formatstring optional |
Controls the format expected for extra_info data transmitted between:
plain_text_array
|
extra_info[object] or string optional |
An array of JSON objects with additional contextual information associated with this authentication attempt. Each JSON object has mandatory key and value attributes. The Futurae app will display this information to the user in the approval details screen, in the order specified in the array.Maximum number of key -value objects accepted for the extra_info array: 20 Maximum length in bytes allowed for each JSON key field: 100 Maximum length in bytes allowed for each JSON value field: 2000 Maximum length in bytes allowed for all JSON key -value pairs together: 2000 When the extra_info_format value is jwe , the extra_info content provided to Futurae is expected to be a string that corresponds to JWE encrypted contents of the extra_info JSON object.Currently supported algorithms:
|
status_callback_urlstring optional |
A URL that Futurae server can call in order to deliver status updates as well as the final result of a particular transaction authentication attempt (also called authentication session). It can be used as an alternative to Query Authentication Status for receiving status updates about an authentication session. The URL will be called as a POST request with the Content-Type header being application/json . The body of the request will be a JSON object containing the following fields: user_id , username , session_id , result , status , status_msg , device_id and user_presence_verification . The user_presence_verification field will only be present if the particular feature is enabled and result is allow . The session ID identifies the particular authentication session and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443. |
mobile_auth_redirect_uristring optional |
When the transaction takes place on a device on which the Futurae mobile app is installed and enrolled (mobile only), this is the redirect URI which the Futurae iOS app will call once transaction authentication is completed. Refer to the mobile only guide for more information on how to use this parameter. |
session_timeoutnumber optional |
A number that indicates the session timeout value in seconds. Minimum: 30 Maximum: 120 Default: 60 (Configurable by the Update Service Information endpoint) |
Response 200
Example response:
200 OK
{
"session_id": "f18b2152-83d6-4a36-b531-98163042c673",
"mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4=",
"mobile_auth_universal_link": "https://futurae.com/futurae_auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}
Request was successful.
Fields | |
---|---|
session_idstring
|
A session ID that identifies the newly created authentication session. It can be used to receive real-time updates regarding the status of the authentication session using Query Authentication Status. |
mobile_auth_uristring
|
A URI which can be used for performing transaction authentication when the transaction takes place on a device on which either the Futurae mobile app, a Whitelabel app or an SDK app is installed and enrolled (mobile only). Refer to the mobile only guide for more information. |
mobile_auth_universal_linkstring
|
Similar to mobile_auth_uri but using a custom domain. Use universal links to ensure seamless redirection to an app or website, improving user experience. Their setup requires domain verification, which enhances trust. Default domain is futurae.com . Subdomains are also supported. To setup the custom domain, contact support@futurae.com. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Request failed. One of the following reasons apply:
- Invalid or missing parameters, for example the specified
user_id
does not exist. - The specified
device_id
does not support the corresponding capability in order to perform authentication using the chosenfactor
, or there was no available device found that supports the capability needed for the chosenfactor
. In these cases, thecode
field within the JSON response will have the value40011
.
Response 403
Example response:
403 Forbidden
{
"error": true,
"code": 40300,
"message": "forbidden"
}
The chosen factor is not in the allowed factors for this user, and cannot be used until it is explicitly allowed for this user (via Modify User). Alternatively, your application can use another factor to authenticate this user.
Abort Authentication
POST /srv/auth/v1/user/auth/abort
Use this endpoint to abort an ongoing authentication, or transaction authentication, session.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"session_id": "f18b2152-83d6-4a36-b531-98163042c673"
}
user_id OR username string optional |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
session_idstring required |
The session ID of the authentication attempt (as returned by Authenticate User or Authenticate Transaction) that will be aborted. |
Response 200
Example response:
200 OK
{
"result": "deny",
"status": "aborted",
"status_msg": "Authentication aborted."
}
Request was successful. The authentication session was aborted.
Fields | |
---|---|
resultstring
|
It will be deny . |
statusstring
|
It will be aborted . |
status_msgstring
|
A string describing the status or result of the authentication attempt. This string is intended for display to the user, although it is advisable that you customize the output to the user, to better tailor the wording to the style of your application. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters. For example, the specified user_id
, username
or session_id
does not exist.
Query Authentication Status
POST /srv/auth/v1/user/auth/status
Your application can use this endpoint to get status updates as well as the result of a particular authentication attempt (also called authentication session). Note that the endpoint returns immediately with the current authentication status, thus you would need to use this endpoint in a poll-based fashion, in order to get informed about a status update. We strongly recommend polling no faster than every 1 second.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"session_id": "f18b2152-83d6-4a36-b531-98163042c673"
}
user_id OR username string optional |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
session_idstring required |
The session ID of the authentication attempt as returned by Authenticate User or Authenticate Transaction. |
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "allow",
"status_msg": "Authentication succeeded.",
"device_id": "d8f517c4-295d-4b02-897b-7cadd56abc54",
"user_id": "e8d7ecf7-75de-4f52-988e-689393662266",
"user_presence_verification": "biometrics_any"
}
Request was successful.
Fields | |
---|---|
resultstring
|
It will be one of the values described in Authentication Result. |
statusstring
|
String detailing the progress or outcome of the authentication attempt. If the authentication attempt was denied, it may identify a reason, and depending on the scenario your application should retry the process. It will be one of the values described in Authentication Status. |
status_msgstring
|
A string describing the status or result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user, although it is advisable that you customize the output to the user, to better tailor the wording to the style of your website. |
device_idstring optional |
This field contains the ID of the user device that was involved in this particular authentication attempt, if it is known. Whether this field will be present depends on the following. If Authenticate User or Authenticate Transaction was invoked with the device_id input param containing a specific device ID or auto (which also maps to a particular device), then that device ID will be returned in this field. The same holds if all was supplied as device_id , or device_id was not supplied at all, nevertheless the user interacted with one of their devices to complete (approve/reject) the authentication attempt. In this case the ID of that particular device will be returned.On the other hand, if all was supplied as device_id , or device_id was not supplied at all, but there was no user device interaction (ie, the authentication attempt timed out or was interrupted) then no device ID will be known and this field will not be present. |
user_idstring optional |
This field contains the ID of the user that was involved in this particular authentication attempt, if it is known. |
trusted_device_tokenstring optional |
This field will be present if the authentication was successful (i.e., result was allow ) and Authenticate User had been called with the set_trusted parameter set to true for this particular session.In this case, this serves as a secure token (cookie) that can be used to mark the device from which the authentication attempt took place as trusted. The token can later be supplied to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from a trusted device. |
user_presence_verificationstring optional |
This field contains information about what kind of biometric was used to authenticate the user. This field will only be present if the particular feature is enabled and result is allow . It can have one of the following values:android_any — Android specific (older versions), any verification method (biometrics or device credentials)app_specific_pin — Verification via the App/SDK-specific PINbiometrics_any — Biometrics of any type. Currently Android specificbiometrics_ios_face_id — Face ID biometrics on iOSbiometrics_ios_touch_id — Touch ID biometrics on iOSdevice_credentials_any — Any non-biometrics screen lock method on Android. Currently Android specificdevice_credentials_ios_passcode — Passcode of any type on iOSios_passcode_or_biometrics — iOS specific biometrics or passcode verification, when the SDK lock configuration is LockConfigurationTypeBiometricsOrPasscode .none — No verification method was used |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters. For example, the specified user_id
, username
or session_id
does not exist.
Query Authentication Status (Deprecated)
POST /srv/auth/v1/user/auth_status
Your application can use this endpoint to get status updates as well as the result of a particular authentication attempt (also called authentication session). This endpoint can return a response in two different ways:
It can wait until the authentication session has been completed and return when the result is available.
It can wait just for the next status update during the authentication session and return the new status. It can then be called once again to either retrieve the next status update or wait for the result to become available (depending on how it's called this time).
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"session_id": "f18b2152-83d6-4a36-b531-98163042c673"
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
session_idstring required |
The session ID of the authentication attempt as returned by Authenticate User or Authenticate Transaction. |
final_resultboolean optional |
If true , block and only return once the authentication process has been completed, reporting the final result.If false , then block only until the next status update during the authentication process occurs and return the new status. The endpoint can then be called once again to retrieve subsequent status updates and eventually the result.Default: false
|
Response 200
Example response:
200 OK
{
"result": "allow",
"status": "allow",
"status_msg": "Authentication succeeded.",
"device_id": "d8f517c4-295d-4b02-897b-7cadd56abc54",
"user_presence_verification": "biometrics_any"
}
Request was successful.
Fields | |
---|---|
resultstring
|
It will be one of the values described in Authentication Result. |
statusstring
|
String detailing the progress or outcome of the authentication attempt. If the authentication attempt was denied, it may identify a reason, and depending on the scenario your application should retry the process. It will be one of the values described in Authentication Status. |
status_msgstring
|
A string describing the status or result of the authentication attempt. If the authentication attempt was denied, it may identify a reason. This string is intended for display to the user, although it is advisable that you customize the output to the user, to better tailor the wording to the style of your website. |
device_idstring optional |
This field contains the ID of the user device that was involved in this particular authentication attempt, if it is known. Whether this field will be present depends on the following. If Authenticate User or Authenticate Transaction was invoked with the device_id input param containing a specific device ID or auto (which also maps to a particular device), then that device ID will be returned in this field. The same holds if all was supplied as device_id , or device_id was not supplied at all, nevertheless the user interacted with one of their devices to complete (approve/reject) the authentication attempt. In this case the ID of that particular device will be returned.On the other hand, if all was supplied as device_id , or device_id was not supplied at all, but there was no user device interaction (ie, the authentication attempt timed out or was interrupted) then no device ID will be known and this field will not be present. |
trusted_device_tokenstring optional |
This field will be present if the authentication was successful (i.e., result was allow ) and Authenticate User had been called with the set_trusted parameter set to true for this particular session.In this case, this serves as a secure token (cookie) that can be used to mark the device from which the authentication attempt took place as trusted. The token can later be supplied to Query Authentication Options, in order to immediately grant access (without performing Futurae authentication), whenever the authentication attempt originates from a trusted device. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters. For example, the specified user_id
, username
or session_id
does not exist.
One-Time Codes
POST /srv/auth/v1/user/one_time_code
Generate a new random one-time code. The code is numerical (only digits) and can be used once by the user to successfully complete Futurae authentication.
Your application is responsible of delivering the passcode to the user using a channel, such as SMS, or e-mail.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"valid_secs": 60
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
lengthnumber optional |
How long (number of digits) the one-time code should be. Minimum: 4 Maximum: 20 Default: 6
|
valid_secsnumber optional |
Time, in seconds, for which the one-time code will remain valid. Minimum: 60 (1 minute)Maximum: 604800 (7 days)Default: 180 (3 minutes) |
Response 200
Example response:
200 OK
{
"one_time_code": "235 094",
"expiration": 1461694259
}
Request was successful.
Fields | |
---|---|
one_time_codestring
|
The newly generated one-time code, formatted with some spacing to make it more readable. |
expirationnumber
|
Time at which this one-time code will expire. Formatted as a Unix timestamp (in seconds). |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the specified user_id
does not exist.
Backup Codes
POST /srv/auth/v1/user/backup_codes
This endpoint clears the entire existing (if any) list of backup authentication codes and generates a fresh list. The codes are numerical (only digits) and generated randomly. Your application should show the codes to the user. The user should store the backup codes safely and use them to authenticate in case he has lost access to his devices.
Body Parameters
Example request body params:
{
"user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
"length": 8,
"reuse_count": 1
}
user_id OR username string required |
ID of the user. OR Username, as specified by your application or generated randomly by Futurae. |
countnumber optional |
How many codes to generate. Minimum: 1 Maximum: 10 Default: 10
|
lengthnumber optional |
How long (number of digits) each code should be. Minimum: 8 Maximum: 20 Default: 10
|
reuse_countnumber optional |
The number of times each of the generated code can be used for authentication. Ideally it should be that they are only used once. If set to 0 , then the codes can be reused infinitely many times (not recommended).Default: 1
|
Response 200
Example response:
200 OK
{
"backup_codes": [
"841 117 648 0",
"330 638 893 6",
"624 896 343 5",
"755 820 701 9",
"875 153 642 6",
"472 728 485 5",
"946 567 429 7",
"204 970 913 6",
"720 670 595 7",
"722 178 105 3"
]
}
Request was successful.
Fields | |
---|---|
backup_codes[string]
|
The newly generated backup codes, formatted with some spacing to make them more readable. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
Invalid or missing parameters, or the specified user_id
does not exist.
Initialize Adaptive Session
POST /srv/auth/v1/user/adaptive/init
This endpoint generates an adaptive session token and initialize the adaptive session. The adaptive session token is a token which uniquely identifies the adaptive session.
The adaptive session expires after 10 minutes of inactivity, when no new observations are submitted. Regardless of how often observations are submitted, the adaptive session will time out after 1 hour.
This endpoint is only available if the User Risk Radar is enabled.
Body Parameters
Example request body params:
{}
Response 201
Example response:
201 Created
{
"adaptive_session_token": "c29tZXJhbmRvbXN0cmluZw"
}
Request was successful.
Fields | |
---|---|
adaptive_session_token[string]
|
The newly generated adaptive session token, which uniquely identifies the adaptive session. |
Response 400
Example response:
400 Bad Request
{
"error": true,
"code": 40000,
"message": "bad request"
}
The User Risk Radar feature is not enabled
Resources
Authentication Result
This is a string
value which describes the result of a particular Futurae authentication attempt. It will have one of the values described in the table below:
Values | |
---|---|
allow |
Authentication was successful. Your application should grant access to the user. |
deny |
Authentication failed. Your application should deny access. Depending on the specific reason, you might need to retry the authentication process, possibly with a different fallback factor. |
waiting |
Authentication is still in-progress (final result is not available yet). |
Authentication Status
This is a string
value which describes the progress or outcome of a particular Futurae authentication attempt. If the authentication attempt was denied, it may identify a reason, and depending on the scenario your application should retry the process. It will have one of the values described in the table below:
Values | |
---|---|
notification_sent |
A One-Touch authentication session has been created and a push notification has been sent to the user’s device. The Authentication Result will be waiting . |
timeout_retry |
Authentication failed due to a timeout. The approve and qr_code factors time out after 1 minute. The user should retry with the same or other factor.The Authentication Result will be deny . |
qr_code_ready |
The QR code authentication session has been created and the QR code is ready to be displayed. The Authentication Result will be waiting . |
qr_code_retry |
An invalid user-supplied code was provided in Validate Offline QR code as part of performing authentication with the offline QR code method. The user has still one or more remaining attempts. The Authentication Result will be waiting . |
interrupted |
Authentication failed. This authentication session was interrupted because a new session was initiated while this session was still in progress. The Authentication Result will be deny . |
aborted |
Authentication failed. This authentication session was explicitly aborted by your application. The Authentication Result will be deny . |
deny |
Authentication failed. The user may retry. The Authentication Result will be deny . |
incompatible_mobile_app |
Authentication failed because the user's mobile app is outdated and not compatible with the current version of the Futurae server. The user should be prompted to update his mobile app to the latest version before attempting to authenticate again. Until this happens, approve and qr_code factors cannot be used on that device. Nevertheless, the mobile one-time codes (for use with the passcode factor) are still functional.The Authentication Result will be deny . |
locked_out |
Authentication failed too many times or his status was programmatically set to this value. User needs to be reset (via Modify User) in order to be able to authenticate again. The Authentication Result will be deny . |
fraud |
The authentication attempt was reported as fraudulent (the user rejected the approval request). The Authentication Result will be deny . |
allow |
Authentication was successful. The Authentication Result will be allow . |
Allowed Factors
Allowed factors are string
values that represent which Futurae authentication technologies a user is eligible to use. The allowed factors of a user can be configured via Modify User.
The table below lists all different factors:
Factors | |
---|---|
approve |
Authentication based on approvals received through push notifications (aka One-Touch). |
fido |
Authentication using FIDO2/WebAuthn. |
mobile_auth |
Single device authentication (aka mobile only), i.e., when the authentication attempt takes place on a device on which the Futurae mobile app is installed and enrolled for this particular user. Refer to the mobile only guide for more information. |
mobile_totp |
Generate time-based one-time codes from within the Futurae mobile app on the user device. |
hwtoken_totp |
Generate time-based one-time codes using a hardware token device. |
passcode |
Authentication based on any type of one-time code (including mobile_totp above). The user-submitted code can be verified with Authenticate with Passcode.
|
qr_code |
Authentication based on QR code scanning. |
sms |
Receive SMS one-time codes (SMS-based authentication). |
sync |
A synchronous OTP based authentication which can be used to authenticate when the attempt takes place on a device with the authenticator app installed. |
Default allowed factors assignments
- By default, new users will be assigned all available factors at the time when they are created.
- The
hwtoken_totp
factor which was introduced in June 2020 (Auth API v1.3.0) is automatically added to the list of allowed factors of a user whenever a TOTP hardware token is assigned to them. - The
fido
factor which was introduced in January 2021 (Auth API v1.5.0) is automatically added to the list of allowed factors of a user whenever a FIDO2/U2F authenticator is enrolled for them.
Device
This resource represents a user device. There are four types of devices:
A device corresponding to a mobile authenticator app, called mobile app device. These devices can support and offer the mobile app-based Futurae authentication factors, such as "approve", "qr_code" and "mobile_totp". The Futurae mobile app, Futurae white-label apps and Futurae mobile SDKs are all considered mobile app devices.
A FIDO2 or FIDO U2F compatible device called FIDO device. These devices support FIDO2 authentication via WebAuthn. External FIDO hardware authenticators (such as YubiKey), known as
cross-platform
or roaming authenticators, or embedded authenticators (such as those offered by iOS, Android and Windows Hello platforms), known asplatform
authenticators, are all considered fido devices.A hardware token, called hardware token device. Refer to Admin API's Hardware Token resource section for more information.
A device that is associated with a phone number, called SMS device. SMS devices only have the "sms" capability and can be used to send SMS one-time codes (SMS-based authentication).
The Device resource is defined in the following table:
Example Device objects:
Mobile app device example:
{
"device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd",
"display_name": "My iphone X",
"capabilities": [
"approve",
"qr_code",
"mobile_totp",
"qr_code"
],
"type": "ios",
"version": "1.0.1",
"version_supported": true,
"account_recovery_flow_binding_enabled": true,
"device_integrity": "jailbroken",
"device_integrity_updated_at": 1715851709
}
FIDO device example:
{
"device_id": "d3085f1c-f8c6-4326-bf5d-b976229785f2",
"display_name": "My security key",
"capabilities": [
"fido"
],
"type": "fido",
"account_recovery_flow_binding_enabled": true
}
Hardware token device example:
{
"device_id": "d0b4746b-1f02-409d-892c-abae473244b7",
"display_name": "GALT10530000",
"capabilities": [
"hwtoken_totp"
],
"hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10",
"type": "hwtoken"
}
SMS device example:
{
"device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
"display_name": "My phone",
"capabilities": [
"sms"
],
"number": "+41123456789"
}
Fields | |
---|---|
device_idstring
|
The ID of this device. |
display_namestring
|
A short, memorable string which can be used to identify the device in a prompt. By default, the display name has the following values according to the type of device:
|
capabilities[string]
|
A list of the available authentication technologies that can be used with this device. See Devices Capabilities for a detailed description. |
typestring optional |
This field is not applicable for SMS devices. It can have the following values:
|
hwtoken_idstring optional |
The ID of the corresponding Hardware Token record. This field is only applicable for hardware token devices. |
versionstring optional |
The currently installed Futurae mobile app version. This field is only applicable for mobile app devices. |
version_supportedboolean optional |
A boolean value indicating whether the currently installed mobile app version is supported by the currently operating version of the Futurae server. If this is false , then it means that the only functional capability of this device is mobile_totp . All other authentication factors will not be usable unless the user updates the mobile app. This field is only applicable for mobile app devices. |
numberstring optional |
The phone number of the device. This field is only applicable for SMS devices. |
migrated_from_device_idstring optional |
The ID of the device this device was migrated from. This field is only applicable for mobile app devices and will be present if this device was automatically enrolled during Automatic Account Recovery from a previous device. |
migrated_to_device_idstring optional |
The ID of the device this device was migrated to. This field is only applicable for mobile app devices and will be present if this device was migrated to a new device during Automatic Account Recovery. |
migrated_atnumber optional |
The time, represented as a Unix timestamp, when this device was migrated to the device with ID migrated_to_device_id . This field is only applicable for mobile app devices and will be present if this device was migrated to a new device during Automatic Account Recovery. |
account_recovery_flow_binding_enabledboolean optional |
Indicates whether Trusted Session Binding is enabled for account recovery. This field is only applicable for mobile app and FIDO devices. |
device_integritystring |
Indicates the integrity status of the device. It can have the following values: meets_integrity , jailbroken , rooted or unknown . This field is only applicable for mobile apps. |
device_integrity_updated_atnumber |
Indicates the date as Unix time, which is the number of seconds elapsed since January 1, 1970 UTC. This field is only applicable for mobile apps. |
Device Capabilities
Device capabilities are string
values that represent which Futurae authentication technologies can be used with the specific device. The following table lists all the different device capabilities:
Values | |
---|---|
approve |
The device supports authentication using approvals sent via push notifications (aka One-Touch). |
fido |
The device supports FIDO authentication. |
mobile_totp |
The device can generate time-based one-time codes from within the Futurae mobile app. |
hwtoken_totp |
The device is a hardware token that can generate time-based one-time codes. |
qr_code |
The device supports authentication based on QR code scanning. This capability is available in the Futurae mobile app as well as hardware tokens with type qr_code . |
sms |
The device can receive SMS one-time codes. |
sync |
The device supports synchronous OTP based authentication |
Enrollment Status
The enrollment status is a string
that represents the status of a Futurae mobile app-based device enrollment which was initiated via Enroll Users and Devices. It will have one of the values described in the table below:
Values | |
---|---|
success |
The user successfully enrolled with a new device. |
expired |
The code expired. |
pending |
The code has not been claimed yet. |
User Status
The user status is a string
that represents the user's current status with respect to Futurae authentication. It will have one of the values described in the table below:
Values | |
---|---|
bypass |
The user can bypass Futurae authentication. This implies that any Futurae authentication attempt for this user will automatically and immediately return allow . |
enabled |
The user has one or more enrolled devices and must complete Futurae authentication using one of them. |
disabled |
The user has no enrolled devices and Futurae authentication is disabled. The user cannot authenticate using Futurae authentication, before he enrolls a new device. |
locked_out |
The user has been locked out due to an excessive amount of failed authentication attempts or his status was programmatically set to this value. This implies that any Futurae authentication attempt for this user will automatically and immediately return deny . His status needs to be reset (via Modify User) in order to be able to authenticate again using Futurae. |
© Copyright 2024 Futurae Technologies AG.