NAV

python ruby go java csharp php javascript

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.

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 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:

  1. 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.

  2. 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:

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:

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:

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

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:

  1. Serialize the unencrypted extra_info into a JSON formatted string.
  2. Decode the base64 encoded extra_info_key.
  3. Create the JWE Compact Serialization of the unencrypted extra_info JSON formatted string, which represents encrypted content as a compact, URL-safe string.
  4. Provide the string resulting of the previous step, as content of the extra_info field, and set the field extra_info_format value to jwe.

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
time
string
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_version
string
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
time
string
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
time
string
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 /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_url
string
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.

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=="
}
logo
string
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_url
string
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
begin
number
required
Begin of the time range formatted as a Unix timestamp in seconds.
end
number
required
End of the time range formatted as a Unix timestamp in seconds.
offset
number
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
}
username
string
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_name
string
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_secs
number
optional
Time, in seconds, for which the activation code will remain valid.
Minimum: 60
Maximum: 7776000 (90 days)
Default: 604800 (7 days)
short_code
boolean
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_url
string
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_enabled
boolean
optional
Set this field to true to enable Trusted Session Binding for this enrollment.
Default: false
account_recovery_flow_binding_enabled
boolean
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_code
string
The activation code.
enrollment_id
string
Enrollment unique ID.
activation_qrcode_url
string
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_uri
string
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_uri
string
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_link
string
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_short
string
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.
expiration
number
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds).
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
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_id
string
required
The permanent, unique ID of the user as generated by Futurae.
valid_secs
number
optional
Time, in seconds, for which the activation code will remain valid.
Minimum: 60
Maximum: 7776000 (90 days)
Default: 604800 (7 days)
short_code
boolean
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_url
string
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_enabled
boolean
optional
Set this field to true to enable Trusted Session Binding for this enrollment.
Default: false
account_recovery_flow_binding_enabled
boolean
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_code
string
The activation code.
enrollment_id
string
Enrollment unique ID.
activation_qrcode_url
string
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_uri
string
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_uri
string
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_link
string
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_short
string
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.
expiration
number
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds).
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
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:

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
}
username
string
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_name
string
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.
fido
boolean
required
This field must be set to true, in order to enroll a FIDO device.
valid_secs
number
optional
Time, in seconds, for which the activation code will remain valid.
Minimum: 60
Maximum: 7776000 (90 days)
Default: 604800 (7 days)
short_code
boolean
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_preference
string
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_selection
object
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_url
string
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_enabled
boolean
optional
Set this field to true to enable Trusted Session Binding for this enrollment.
Default: false
account_recovery_flow_binding_enabled
boolean
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_code
string
The activation code. Suitable for use in the implicit approach explained above.
enrollment_id
string
Enrollment unique ID.
activation_code_short
string
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.
expiration
number
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds).
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
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:

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_id
string
required
The permanent, unique ID of the user as generated by Futurae.
fido
boolean
required
This field must be set to true, in order to enroll a FIDO device.
valid_secs
number
optional
Time, in seconds, for which the activation code will remain valid.
Minimum: 60
Maximum: 7776000 (90 days)
Default: 604800 (7 days)
short_code
boolean
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_preference
string
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_selection
object
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_url
string
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_enabled
boolean
optional
Set this field to true to enable Trusted Session Binding for this enrollment.
Default: false
account_recovery_flow_binding_enabled
boolean
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_code
string
The activation code. Suitable for use in the implicit approach explained above.
enrollment_id
string
Enrollment unique ID.
activation_code_short
string
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.
expiration
number
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds).
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
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"
}
username
string
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_name
string
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_id
string
required
The ID of the Hardware Token that will be enrolled for this user.
hwtoken_passcode
string
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_id
string
The ID of the newly created hardware token device.
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
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:

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_id
string
required
The permanent, unique ID of the user as generated by Futurae.
hwtoken_id
string
required
The ID of the Hardware Token that will be enrolled for this user.
hwtoken_passcode
string
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_id
string
The ID of the newly created hardware token device.
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
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:

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"
}
username
string
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_name
string
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_number
string
required
The phone number of the device in international format.
trusted_phone_number
bool
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_id
string
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_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
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_id
string
required
The permanent, unique ID of the user as generated by Futurae.
phone_number
string
required
The phone number of the device in international format.
trusted_phone_number
bool
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_id
string
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_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
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
result
string
Status of the enrollment. It will be one of the values described in Enrollment Status.
device_id
string
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_id
string
required
The device ID, as returned from Enroll Users and Devices.
action
string
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_text
string
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.
passcode
string
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
result
string
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
username
string
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_id
string
The permanent, unique identifier of the user in Futurae.
username
string
The username of this user.
status
string
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
username
string
The username of this user. This serves as an alternative identifier which can be specified by your application, or generated randomly by Futurae.
display_name
string
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.
status
string
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_at
number
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.
status
string
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).
username
string
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_name
string
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_attempts
number
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.
status
string
optional
The user status, if updated. It will be one of the values described in User Status.
username
string
optional
The username, if updated.
display_name
string
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_id
string
required
The ID of the device that will be unenrolled.

Response 200

Example response:

200 OK
{
    "result": "success"
}

Request was successful.

Fields
result
string
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_name
string
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_enabled
boolean
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"
}
version
number
required
Current supported version is 1.
valid_secs
number
optional
Time, in seconds, for which the token will remain valid.
Minimum: 1
Maximum: 600 (10 mins)
Default: 120 (2 mins)
flow
string
required
The flow, for which the Trusted Session Binding token will be created. Current supported values: enrollment and account_recovery.
activation_code
string
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_token
string
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
result
string
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_factor
string
optional
The factor to use for authentication as recommended by Futurae, and based on the capabilities of the user's devices.
user_status
string
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_at
number
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.
factor
string
required
Must be approve.
device_id
string
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_fallback
boolean
optional
Set this param to true to combine One-Touch with an offline QR code session which will serve as fallback.
Default: false
type
string
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_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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_uri
string
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_trusted
boolean
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_days
number
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_timeout
number
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_id
string
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_uri
string
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_link
string
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_id
string
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_uri
string
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_link
string
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_value
int
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_id
string
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_uri
string
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_link
string
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_id
string
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_url
string
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_uri
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

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.
factor
string
required
Must be mobile_auth.
device_id
string
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.
type
string
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_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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_uri
string
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_trusted
boolean
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_days
number
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_timeout
number
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_id
string
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_uri
string
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_link
string
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:

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.
factor
string
required
Must be sync.
device_id
string
required
The ID of the device to use for this particular authentication attempt. The device must support the sync capability (see Device Capabilities).
token
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

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.
factor
string
required
Must be fido.
device_id
string
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_verification
string
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_url
string
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_trusted
boolean
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_days
number
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_timeout
number
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_id
string
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_token
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

Response 403

Example response:

403 Forbidden
{
    "error": true,
    "code": 40300,
    "message": "forbidden"
}

Operation is forbidden. One of the following reasons apply:

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.
factor
string
required
Must be passcode.
passcode
string
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_trusted
boolean
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_days
number
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
result
string
Either allow or deny. See Authentication Result for details.
status
string
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_msg
string
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_type
string
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_id
string
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_token
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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.
factor
string
required
Must be qr_code.
extra_info_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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_uri
string
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_trusted
boolean
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_days
number
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_timeout
number
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_id
string
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_url
string
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_uri
string
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_uri
string
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_link
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

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.
factor
string
required
Must be qr_code.
offline
boolean
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_id
string
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:
  • Optional when using a mobile app device, i.e., you can omit supplying a device ID and instead can use any of the user's enrolled mobile app devices.
  • Mandatory when using a hardware token device. In this case you must specify the device id of the hardware token that will be used for this operation.
extra_info_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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_trusted
boolean
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_days
number
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_id
string
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_url
string
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_uri
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

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.
factor
string
required
Must be qr_code.
passcode
string
required
The code supplied by the user.
session_id
string
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
result
string
It will be waiting.
status
string
It will be qr_code_retry.
status_msg
string
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
result
string
It will be deny.
status
string
It will be deny.
status_msg
string
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_id
string
The ID of the authenticator device.
result
string
It will be allow.
status
string
It will be allow.
status_msg
string
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:

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"
}
factor
string
required
Must be usernameless_qr_code.
extra_info_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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.
type
string
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_timeout
number
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_uri
string
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_url
string
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_id
string
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:

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.
factor
string
required
Must be sms.
device_id
string
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_text
string
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_secs
number
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_trusted
boolean
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_days
number
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
result
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

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.
factor
string
required
Must be approve.
device_id
string
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_fallback
boolean
optional
Set this param to true to combine One-Touch with an offline QR code session which will serve as fallback.
Default: false
type
string
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_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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_uri
string
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_timeout
number
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_id
string
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_uri
string
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_link
string
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_id
string
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_uri
string
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_link
string
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_id
string
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_url
string
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_uri
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

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.
factor
string
required
Must be qr_code.
extra_info_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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_uri
string
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_timeout
number
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_id
string
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_url
string
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_uri
string
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_uri
string
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_link
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

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.
factor
string
required
Must be qr_code.
offline
boolean
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_id
string
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:
  • Optional when using a mobile app device, i.e., you can omit supplying a device ID and instead can use any of the user's enrolled mobile app devices.
  • Mandatory when using a hardware token device. In this case you must specify the device id of the hardware token that will be used for this operation.
extra_info_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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_id
string
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_url
string
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_uri
string
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
result
string
Either allow or deny:

allow — Your application should grant access to the user.

deny — Your application should deny access to the user.
status
string
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_msg
string
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:

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.
factor
string
required
Must be mobile_auth.
device_id
string
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.
type
string
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_format
string
optional
Controls the format expected for extra_info data transmitted between:
  • The Customer Backend and the Futurae backend
  • A mobile application and the Futurae backend.
Valid values:
  • plain_text_array: The extra_info is expected to be an array of JSON objects (See extra_info below).
  • jwe: The extra_info is expected to be the string of the JWE-encrypted JSON representation of the extra_info content.
Default: 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:
  • Algorithm: A256KW
  • Encryption: A256GCM
status_callback_url
string
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_uri
string
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_timeout
number
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_id
string
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_uri
string
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_link
string
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:

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_id
string
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
result
string
It will be deny.
status
string
It will be aborted.
status_msg
string
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_id
string
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
result
string
It will be one of the values described in Authentication Result.
status
string
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_msg
string
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_id
string
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_id
string
optional
This field contains the ID of the user that was involved in this particular authentication attempt, if it is known.
trusted_device_token
string
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_verification
string
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 PIN

biometrics_any — Biometrics of any type. Currently Android specific

biometrics_ios_face_id — Face ID biometrics on iOS

biometrics_ios_touch_id — Touch ID biometrics on iOS

device_credentials_any — Any non-biometrics screen lock method on Android. Currently Android specific

device_credentials_ios_passcode — Passcode of any type on iOS

ios_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:

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_id
string
required
The session ID of the authentication attempt as returned by Authenticate User or Authenticate Transaction.
final_result
boolean
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
result
string
It will be one of the values described in Authentication Result.
status
string
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_msg
string
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_id
string
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_token
string
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.
length
number
optional
How long (number of digits) the one-time code should be.
Minimum: 4
Maximum: 20
Default: 6
valid_secs
number
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_code
string
The newly generated one-time code, formatted with some spacing to make it more readable.
expiration
number
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.
count
number
optional
How many codes to generate.
Minimum: 1
Maximum: 10
Default: 10
length
number
optional
How long (number of digits) each code should be.
Minimum: 8
Maximum: 20
Default: 10
reuse_count
number
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

Device

This resource represents a user device. There are four types of devices:

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_id
string
The ID of this device.
display_name
string
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:
  • For a mobile app device, it's the device model.
  • For a FIDO device, the word fido.
  • For a hardware token, its serial number.
  • For an SMS device, the phone number.
capabilities
[string]
A list of the available authentication technologies that can be used with this device. See Devices Capabilities for a detailed description.
type
string
optional
This field is not applicable for SMS devices. It can have the following values:
  • android for Android mobile devices.
  • ios for iOS mobile devices.
  • fido for FIDO devices.
  • hwtoken for hardware token devices.
hwtoken_id
string
optional
The ID of the corresponding Hardware Token record. This field is only applicable for hardware token devices.
version
string
optional
The currently installed Futurae mobile app version. This field is only applicable for mobile app devices.
version_supported
boolean
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.
number
string
optional
The phone number of the device. This field is only applicable for SMS devices.
migrated_from_device_id
string
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_id
string
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_at
number
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_enabled
boolean
optional
Indicates whether Trusted Session Binding is enabled for account recovery. This field is only applicable for mobile app and FIDO devices.
device_integrity
string
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_at
number
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.