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:

Request Format

For calling the API endpoints, the request URI consists of the Service hostname, the Auth API version prefix and the endpoint together with any potential parameters (each endpoint showcases an example URI on how to call it).

Headers

Each request must contain an FT-Date header, containing the current time formatted as RFC 2822 and an Authorization header (see Request Authentication on how to construct the Authorization header in order to authenticate each request).

Parameters

For GET and DELETE requests any parameters must be URL-encoded and sent in the URL query string.

For POST and PUT requests, the header Content-Type: application/json must be supplied and the parameters must be sent in the request body as JSON-formatted key/value pairs. For example:

{"user_id":"70d63df1-d20d-4530-ac92-aa6f9f6f329e","valid_secs":86400}

Input Field Restrictions

The following input fields are restricted in terms of maximum length and characters that they may contain.

• username (maximum length: 100 characters): Can be a string with no spaces and with case-sensitive letters ([a-zA-Z]), numbers, or the characters . _ - = @ # $ +

• display_name (maximum length: 100 characters): Can be a string with spaces and with case-sensitive Unicode letters (Unicode L character class), Unicode punctuation (Unicode P character class), numbers, or the characters = @ # $ +

Request Authentication

In order to successfully call the API endpoints you need to authenticate your requests, by signing them using your Auth API key as the signing key. The supplied Authorization header must carry the required signature using the HTTP Basic Authentication format as follows:

Authorization header format:

Authorization: Basic base64( Service_ID:hex( hmac( Auth_API_Key, request_content ) ) )

• The HTTP username will be your Service ID.
• The HTTP password will be a hex-formatted HMAC-SHA256 signature, computed over the request content in the way described below, using the Auth API key as the HMAC key.
• The HTTP username and password are concatenated using a colon, and the concatenated string is Base64 encoded.

The signature must be computed over an ASCII string, consisting of the following request components, which must be concatenated with newline characters ('\n'):

To compute the HMAC signature, use this code:

Copy#############################################
# 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()}

Copyrequire '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

Copyimport (
    "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)
}

Copyimport 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);
    }
}

Copyusing 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));
        }
    }
}

Copy/*
 * 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);
}

Copyvar 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};
};

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:

• Service ID: 5f21ab85-af2f-11e7-9c0d-784f43834446
• Auth API key: GhYZvjGJVyBgeSXVMyUD5G4YR7Y2PzutGhp/MwUt

And that the date is:

Mon, 16 Oct 2017 12:15:34 -0000

Then, the ASCII string on which the signature must be computed is:

Mon, 16 Oct 2017 12:15:34 -0000\nGET\napi-pilot.futurae.com\n/srv/auth/v1/server/test?testparam=testvalue\n\n

And represented as a byte sequence:

77, 111, 110, 44, 32, 49, 54, 32, 79, 99, 116, 32, 50, 48, 49, 55, 32, 49, 50, 58, 49, 53, 58, 51, 52, 32, 45, 48, 48, 48, 48, 10, 71, 69, 84, 10, 97, 112, 105, 45, 112, 105, 108, 111, 116, 46, 102, 117, 116, 117, 114, 97, 101, 46, 99, 111, 109, 10, 47, 115, 114, 118, 47, 97, 117, 116, 104, 47, 118, 49, 47, 115, 101, 114, 118, 101, 114, 47, 116, 101, 115, 116, 63, 116, 101, 115, 116, 112, 97, 114, 97, 109, 61, 116, 101, 115, 116, 118, 97, 108, 117, 101, 10, 10

Notice the two newline characters at the end, which occurs because the request has an empty body.

The resulting HMAC-SHA256 signature in hexadecimal notation will be:

910ef81f5fcf092d203e77ead93a3896092e4953c9cbb41c3e792e8d0b417168

Then we concatenate this together with the Service ID:

5f21ab85-af2f-11e7-9c0d-784f43834446:910ef81f5fcf092d203e77ead93a3896092e4953c9cbb41c3e792e8d0b417168

And encode in base64:

NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjkxMGVmODFmNWZjZjA5MmQyMDNlNzdlYWQ5M2EzODk2MDkyZTQ5NTNjOWNiYjQxYzNlNzkyZThkMGI0MTcxNjg=

Finally, the resulting request will be:

GET /srv/auth/v1/server/test?testparam=testvalue HTTP/1.1
FT-Date: Mon, 16 Oct 2017 12:15:34 -0000
Authorization: Basic NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjkxMGVmODFmNWZjZjA5MmQyMDNlNzdlYWQ5M2EzODk2MDkyZTQ5NTNjOWNiYjQxYzNlNzkyZThkMGI0MTcxNjg=
Host: api-pilot.futurae.com

Example 2: POST Request

Suppose we want to send the following request to the server:

POST https://api-pilot.futurae.com/srv/auth/v1/server/test

with body:

{"testparam":"testvalue"}

Also, suppose that we have the following Service credentials:

• Service ID: 5f21ab85-af2f-11e7-9c0d-784f43834446
• Auth API key: GhYZvjGJVyBgeSXVMyUD5G4YR7Y2PzutGhp/MwUt

And that the date is:

Mon, 16 Oct 2017 12:15:34 -0000

Then, the ASCII string on which the signature must be computed is:

Mon, 16 Oct 2017 12:15:34 -0000\nPOST\napi-pilot.futurae.com\n/srv/auth/v1/server/test\n{"testparam":"testvalue"}\n

And represented as a byte sequence:

77, 111, 110, 44, 32, 49, 54, 32, 79, 99, 116, 32, 50, 48, 49, 55, 32, 49, 50, 58, 49, 53, 58, 51, 52, 32, 45, 48, 48, 48, 48, 10, 80, 79, 83, 84, 10, 97, 112, 105, 45, 112, 105, 108, 111, 116, 46, 102, 117, 116, 117, 114, 97, 101, 46, 99, 111, 109, 10, 47, 115, 114, 118, 47, 97, 117, 116, 104, 47, 118, 49, 47, 115, 101, 114, 118, 101, 114, 47, 116, 101, 115, 116, 10, 123, 34, 116, 101, 115, 116, 112, 97, 114, 97, 109, 34, 58, 34, 116, 101, 115, 116, 118, 97, 108, 117, 101, 34, 125, 10

The resulting HMAC-SHA256 signature in hexadecimal notation will be:

7132afde8b6a3ec25ac3f56ec62c633bde998379688547942248c431d8019b43

Then we concatenate this together with the Service ID:

5f21ab85-af2f-11e7-9c0d-784f43834446:7132afde8b6a3ec25ac3f56ec62c633bde998379688547942248c431d8019b43

And encode in base64:

NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjcxMzJhZmRlOGI2YTNlYzI1YWMzZjU2ZWM2MmM2MzNiZGU5OTgzNzk2ODg1NDc5NDIyNDhjNDMxZDgwMTliNDM=

Finally, the resulting request will be:

POST /srv/auth/v1/server/test HTTP/1.1
FT-Date: Mon, 16 Oct 2017 12:15:34 -0000
Authorization: Basic NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjcxMzJhZmRlOGI2YTNlYzI1YWMzZjU2ZWM2MmM2MzNiZGU5OTgzNzk2ODg1NDc5NDIyNDhjNDMxZDgwMTliNDM=
Content-Type: application/json
Host: api-pilot.futurae.com
Content-Length: 25
{"testparam":"testvalue"}

Callback Authentication

Certain API endpoints, such as Enroll Users and Devices, Authenticate User and Authenticate Transaction, offer the ability to receive results via HTTP POST callbacks. The callback URL needs to be supplied as an input parameter when invoking each relevant endpoint.

Your application must verify the authenticity of each incoming callback request, to ensure that it comes from the Futurae backend. One way to achieve this is to supply a token or nonce (random, high-entropy unguessable value, only used once) as part of the callback URL:

https://www.domain.com/callback?token=alongrandomstringforextrasecurity

JWS Signatures

Moreover, the Auth API offers callback payload verification using detached JWS signatures.

The server uses the Service Callback Signature key (which you can get from Futurae Admin) to compute a JWS signature over the HTTP body payload of the callback, using HS256 (HMAC-SHA256) as the specified algorithm. The detached JWS signature (detached means that the payload representation is missing from the JWS) is appended in the HTTP header x-jws-signature. For example:

x-jws-signature: eyJhbGciOiJIUzI1NiJ9..NsolKSrrFivUFZx_qixwfrogkrpdkz54QyiWlosngwQ

To verify the JWS signature, perform the following steps:

Step 1. To construct the full (non-detached) JWS signature, convert the request body to URL-safe base64 and insert the resulting string in the correct position in the detached JWS, between the two dots, as illustrated in the example below:

eyJhbGciOiJIUzI1NiJ9.base64url(HTTP_request_body).NsolKSrrFivUFZx_qixwfrogkrpdkz54QyiWlosngwQ

Step 2. Verify the JWS signature using the Callback Signature key, and HS256 as algorithm.

Response Format

All responses are formatted as JSON objects (the header Content-Type: application/json is always present in the responses).

Successful responses return a HTTP 200 response code and, depending on the endpoint and its parameters, the JSON response will contain the corresponding fields. In some cases, the response might contain nested JSON arrays and/or objects. Refer to each individual endpoint to check the format of the endpoint's successful responses.

This is how an unsuccessful response payload looks like:

Copy{
    "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.

End-to-end encryption for extra_info

Futurae Authenticate User and Authenticate Transaction endpoints support extra_info data End-to-End encryption:

• The Customer backend encrypts the extra_info and the send it encrypted to Futurae backend.
• The mobile application receives the encrypted extra_info from the Futurae backend, and decrypts it

If End-to-End encryption is enabled for your Service, authentication contextual information can be provided to Futurae in the encrypted format. For that, set the extra_info_format attribute value as jwe, and encrypt the extra_info content before providing it Futurae when starting an authentication. If extra_info_format attribute is not specified, or set as plain_text_array, the extra_info content needs to be provided in plain JSON format.

Endpoints supporting extra_info data end-to-end encryption

• Authenticate with One-Touch
• Authenticate with Mobile Auth
• Authenticate with QR Code
• Authenticate with Offline QR Code
• Authenticate with Usernameless QR Code
• Authenticate Transaction with One
• Authenticate Transaction with QR Code
• Authenticate Transaction with Offline QR Code
• Authenticate Transaction with Mobile Auth

Symmetric key

A base64 encoded symmetric key extra_info_key can be found at Futurae Admin. This key is used to encrypt the extra_info content, according to the steps described in the extra_info encryption procedure section. The extra_info_key is a Service level key, in other words, every Futurae Service has a distinct extra_info_key.

extra_info encryption procedure

This is the outline of the extra_info encryption procedure:

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

Copy{
    "time": "1461694259294"
}

Request was successful.

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

Copy{
    "api_version": "1.0.0"
}

Request was successful.

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

Copy{
    "time": "1461694259294"
}

Request was successful.

Response 401

Example response:

401 Unauthorized

Copy{
  "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:

Copy{  
   "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

Copy{
    "time": "1461694259294"
}

Request was successful.

Response 401

Example response:

401 Unauthorized

Copy{
  "error": true,
  "code": 40100,
  "message": "authorization data missing or invalid",
  "detail": "Authorization failed. HMAC verification failed:\n--DEBUG INFO START--\n----CONTENT TO BE SIGNED----\nTue, 20 Nov 2018 09:34:29 +0100\nGET\napi.futurae.com\n/srv/auth/v1/server/test\n\n-----CONTENT BYTES------\n[84 117 101 44 32 50 48 32 78 111 118 32 50 48 49 56 32 48 57 58 51 52 58 50 57 32 43 48 49 48 48 10 71 69 84 10 97 112 105 46 102 117 116 117 114 97 101 46 99 111 109 10 47 115 114 118 47 97 117 116 104 47 118 49 47 115 101 114 118 101 114 47 116 101 115 116 10 10]\n--DEBUG INFO END--"
}

Authorization failure. The response body will contain additional information in order to help you identify the reason of the failure.

Service

Endpoints related to Service account information and configuration.

Get Stored Logo

GET /srv/auth/v1/service/logo

Get a direct download URL of the logo which is displayed in the Futurae mobile app.

Response 200

Example response:

200 OK

Copy{
    "logo_url": "https://api.futurae.com/logos/YZDHoB-GQhS4SQ37k8iaWqSXshNvwekrw36MbdqZzLSH7L5b7IRkdw=="
}

Request was successful.

Response 404

Example response:

404 Not Found

Copy{
  "error": true,
  "code": 40100,
  "message": "not found"
}

No logo is currently stored on Futurae. Use Upload New Logo to upload a logo.

Upload New Logo

POST /srv/auth/v1/service/logo

Upload a new logo to display in the Futurae mobile app. The previously uploaded logo, if any, will be deleted and replaced by the new logo.

Body Parameters

Example request body params:

Copy{
    "logo": "iVBORw0KGgoAAAANSU...(truncated)...bJP/DxeklQAAAABJRU5ErkJggg=="
}

Response 200

Example response:

200 OK

Copy{
    "logo_url": "https://api.futurae.com/logos/YZDHoB-GQhS4SQ37k8iaWqSXshNvwekrw36MbdqZzLSH7L5b7IRkdw=="
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
  "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

Response 200

Example response:

200 OK

Copy{
    "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

Copy{
  "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:

Copy{
    "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
}

Response 200

Example response:

200 OK

Copy{
  "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.

Response 400

Example response:

400 Bad Request

Copy{
  "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:

Copy{
    "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
}

Response 200

Example response:

200 OK

Copy{
  "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.

Response 400

Example response:

400 Bad Request

Copy{
  "error": true,
  "code": 40000,
  "message": "bad request"
}

Invalid or missing parameters, or the supplied user_id does not exist.

Enroll New User with FIDO Device

POST /srv/auth/v1/user/enroll

Create a new user in Futurae and at the same time get an activation code in order to enroll a FIDO device for this user. The activation code can be returned in two forms, default (long) and short, and has to be passed as argument when calling WebAuthnJS SDK's enroll() method, in order to start the activation process on the client side. You can use the activation code in two different ways for enrolling the FIDO device:

• Implicit: Pass the activation code to WebAuthnJS SDK's enroll() method in the background. The user will be able to activate his FIDO authenticator, being completely unaware of the activation code. This approach assumes that the enrollment process is sufficiently authenticated and/or attacker-free.
• Explicit: Get a short version of the activation code by supplying the short_code input param as true. Deliver the short activation code to the user using an out-of-band channel. When the user is about to activate his FIDO device, ask the user to supply the code and pass the supplied value to WebAuthnJS SDK's enroll() method. This approach increases the security of the FIDO registration step, and is useful when the activation process is not sufficiently authenticated or the risk that the attacker might be able to hijack the activation process is not acceptable.

Body Parameters

Example request body params:

Copy{
    "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
}

Response 200

Example response:

200 OK

Copy{
    "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.

Response 400

Example response:

400 Bad Request

Copy{
  "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

Copy{
    "error": true,
    "code": 40300,
    "message": "forbidden"
}

This operation is not permitted because the Service doesn't have an associated WebAuthn RP Configuration. Call Admin API's Create RP Configuration to create it.

Enroll New FIDO Device for Existing User

POST /srv/auth/v1/user/enroll

This endpoint returns an activation code in order to enroll a FIDO device for an existing Futurae user. The activation code can be returned in two forms, default (long) and short, and has to be passed as argument when calling WebAuthnJS SDK's enroll() method, in order to start the activation process on the client side. You can use the activation code in two different ways for enrolling the FIDO device:

• Implicit: Pass the activation code to WebAuthnJS SDK's enroll() method in the background. The user will be able to activate his FIDO authenticator, being completely unaware of the activation code. This approach assumes that the enrollment process is sufficiently authenticated and/or attacker-free.
• Explicit: Get a short version of the activation code by supplying the short_code input param as true. Deliver the short activation code to the user using an out-of-band channel. When the user is about to activate his FIDO device, ask the user to supply the code and pass the supplied value to WebAuthnJS SDK's enroll() method. This approach increases the security of the FIDO registration step, and is useful when the activation process is not sufficiently authenticated or the risk that the attacker might be able to hijack the activation process is not acceptable.

Body Parameters

Example request body params:

Copy{
    "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
}

Response 200

Example response:

200 OK

Copy{
    "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.

Response 400

Example response:

400 Bad Request

Copy{
  "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

Copy{
    "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:

Copy{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10"
}

Response 200

Example response:

200 OK

Copy{
    "device_id": "d8f517c4-295d-4b02-897b-7cadd56abc54",
    "user_id": "40de80c1-68fe-42ba-b68e-2152940dbf31",
    "username": "someuser@domain.com"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
  "error": true,
  "code": 40000,
  "message": "bad request"
}

Example response (TOTP verification failed):

400 Bad Request

Copy{
  "error": true,
  "code": 40050,
  "message": "bad request"
}

Request failed. One of the following reasons apply:

• Invalid or missing parameters.
• A user with the specified username already exists.
• The specified hwtoken_id does not exist or has been archived.
• The specified hwtoken_id cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization. In this case, the code field within the JSON response will have the value 40051.
• The supplied hwtoken_passcode verification failed against the specified hwtoken_id. In this case, the code field within the JSON response will have the value 40050.

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:

Copy{
    "user_id": "40de80c1-68fe-42ba-b68e-2152940dbf31",
    "hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10"
}

Response 200

Example response:

200 OK

Copy{
    "device_id": "d8f517c4-295d-4b02-897b-7cadd56abc54",
    "user_id": "40de80c1-68fe-42ba-b68e-2152940dbf31",
    "username": "someuser@domain.com"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
  "error": true,
  "code": 40000,
  "message": "bad request"
}

Example response (TOTP verification failed):

400 Bad Request

Copy{
  "error": true,
  "code": 40050,
  "message": "bad request"
}

Request failed. One of the following reasons apply:

• Invalid or missing parameters.
• The specified hwtoken_id does not exist or has been archived.
• The specified hwtoken_id cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization. In this case, the code field within the JSON response will have the value 40051.
• The supplied hwtoken_passcode verification failed against the specified hwtoken_id. In this case, the code field within the JSON response will have the value 40050.

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:

Copy{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "phone_number": "+41123456789"
}

Response 200

Example response:

200 OK

Copy{
  "device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "username": "someuser@domain.com"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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

Copy{
  "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:

Copy{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "phone_number": "+41123456789"
}

Response 200

Example response:

200 OK

Copy{
  "device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "username": "someuser@domain.com"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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

Copy{
  "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:

Copy{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002"
}

Response 200

Example response:

200 OK

Copy{
    "result": "success",
    "device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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:

Copy{
    "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:

Copy{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
    "action": "verify",
    "passcode": "495278"
}

Response 200

Example response:

200 OK

Copy{
    "result": "sent"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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

Copy{
  "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

Response 200

Example response:

200 OK

Copy{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "username": "someone@domain.com",
    "status": "enabled"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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

Copy{
    "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.

Response 400

Example response:

400 Bad Request

Copy{
    "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:

Copy{
    "allowed_factors": ["mobile_totp", "approve", "passcode"],
    "status": "enabled",
    "username": "newusername@domain.com",
    "display_name": "Cooler display name",
    "max_attempts": 15
}

Response 200

Example response:

200 OK

Copy{
    "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.

Response 400

Example response:

400 Bad Request

Copy{
    "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:

Copy{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "device_id": "5bde7d1f-206b-4857-877d-f314912b83f0"
}

Response 200

Example response:

200 OK

Copy{
    "result": "success"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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:

Copy{
    "display_name": "My Android phone",
    "account_recovery_flow_binding_enabled": true
}

Response 200

Example response:

200 OK

Copy{
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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:

Copy{
  "version": 1,
  "valid_secs": 120,
  "flow": "enrollment",
  "activation_code": "NUhiSXk4eF9LRVE3SXdFZDZvRmVUeFd4Qy1BWGtPUlJZX1JnM0ctZm1EQWk6N2E3ZjUyMDktZWUwOS00ZDU0LThlYzAtY2Y2MTAyYjVmNGI2OmFwaS10ZXN0LmZ1dHVyYWUuY29t"
}

Response 201

Example response:

201 Created

Copy{
  "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.

Response 400

Example response:

400 Bad Request

Copy{
    "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.

Send Custom In-App Message

POST /srv/auth/v1/user/notifications/app_notification

Send a push notification to the user's mobile device, which can be displayed to the user by the app. This endpoint will return a notification_id and the list of devices to which the notification was sent with the corresponding gateway statuses.

Body Parameters

Example request body params:

Copy{
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "device_id": "all",
  "ttl_seconds": 1800,
  "payload":{"location":"Zurich region", "warning":"A new device has been enrolled".}
}

Response 200

Example response:

200 Success

Copy{
    "notification_id": "7aca4f7e-4f2f-49d6-8953-969261887287",
    "push_notifications_status": [
        {
            "device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd",
            "gateway_status": null,
            "success": false
        },
        {
            "device_id": "d8f517c4-295d-4b02-897b-7cadd56abc54",
            "gateway_status": 200,
            "success": true
        }
     ]
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "error": true,
    "code": 40000,
    "message": "bad request"
}

Invalid or missing parameters. For example, the specified device_id does not exist, the ttl_seconds or the payload size exceed the maximum allowed values.

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:

Copy{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "trusted_device_token": "ExANyywJKiI7oNCo YE9FnjVbJZW3QlPY2LFxDBx8CXU="
}

Response 200

Example responses:

200 OK

Copy{
    "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

Copy{
    "result": "deny",
    "user_status": "disabled"
}

200 OK

Copy{
    "result": "allow",
    "user_status": "bypass"
}

Request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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:

Copy{
    "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
}

Response 200

Example response:

200 OK

Copy{
  "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.

Response 200

Example response:

200 OK

Copy{
  "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.

Response 200

Example response:

200 OK

Copy{

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

Response 200

Example response:

200 OK

Copy{
    "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.

Response 400

Example response:

400 Bad Request

Copy{
    "error": true,
    "code": 40000,
    "message": "bad request"
}

Request failed. One of the following reasons apply:

• Invalid or missing parameters, for example the specified user_id does not exist.
• The specified device_id does not support the corresponding capability in order to perform authentication using the chosen factor, or there was no available device found that supports the capability needed for the chosen factor. In these cases, the code field within the JSON response will have the value 40011.

Response 403

Example response:

403 Forbidden

Copy{
    "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:

Copy{
    "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
}