NAV Navbar
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.1.1

Version History (change log)

Getting Started

In order to be able to use the Auth API for your Service you will need to get your Service ID, Auth API key and Service hostname.

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.

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 2
#############################################

import base64, email, hmac, json, hashlib

def signpython2(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, data, hashlib.sha256)
    auth = '%s:%s' % (sid, sig.hexdigest())

    return {'FT-Date': now, 'Authorization': 'Basic %s' % base64.b64encode(auth)}


#############################################
# Python 3
#############################################

import base64, email, hmac, json, hashlib

def signpython3(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 java.io.IOException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.text.SimpleDateFormat;
import java.util.Base64;
import java.util.Locale;
import java.util.*;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Sign {
  static String rfc2822Pattern = "EEE, dd MMM yyyy HH:mm:ss Z";
  static SimpleDateFormat rfc2822 = new SimpleDateFormat(rfc2822Pattern, 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 serviceID, String skey) throws IOException {
    params = (params == null) ? "" : params;
    String date = rfc2822.format(new Date());
    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;
    try {
      sig = bytesToHex(digest(data.toString(), skey));
    } catch (Exception e) {
      e.printStackTrace();
      throw new IOException("Crypto error while computing HMAC request signature");
    }

    String auth = serviceID + ":" + sig;

    Map<String, String> headers = new HashMap<String, String>();
    headers.put("FT-Date", date);
    headers.put("Authorization", "Basic " + Base64.getEncoder().encodeToString(auth.getBytes()));

    return headers;
  }

  private static byte[] digest(String content, String skey) throws NoSuchAlgorithmException, InvalidKeyException {
    byte[] contentBytes = content.getBytes();
    Mac mac = Mac.getInstance("HMACSHA256");
    SecretKeySpec macKey = new SecretKeySpec(skey.getBytes(), "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"}

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

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
number
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
number
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
number
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_uri": "futurae://enroll?activation_code=Tf9T5Cl1ffnkDSiD0AmWizbSxxHABbIsYr3bMn14HYU=",
            "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="
        },
        {
            "activation_code_uri": "futurae://enroll?activation_code=JyEBs1p4JyCU6p0GEJ-mhKgaUIw3ny0t4R6FTNRrf10=",
            "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="
        }
    ]
}

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 four distinct enrollment cases, depending on whether you wish to enroll a new user and device, or a device for an existing user, and whether you are enrolling a device with the Futurae app installed for use with app-based factors, such as SoundProof, or the phone number of a device that can be used to for SMS-based authentication.

Enroll a New User

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 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"
}
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.
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)
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 over https.

Response 200

Example response:

200 OK
{
  "activation_code_uri": "futurae://enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "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_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_code_uri
string
The activation code in the form of a URI prefixed with the futurae:// scheme. 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).
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 a New Device for an 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"
}

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)
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 over https.

Response 200

Example response:

200 OK
{
  "activation_code_uri": "futurae://enroll?activation_code=bXR3SExHMERlMHJlQ1pRWmFxcGwwQmxSRWZUd3dmS2VvOGU4dWpEZlIxdzplM2YyOWQ5Zi04MjRkLTQ4N2ItODg5MS0zZmI5NTY4NTE4YjI6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "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_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_code_uri
string
The activation code in the form of a URI prefixed with the futurae:// scheme. 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).
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 a New User with Phone Number

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.
See the input restrictions that apply.
phone_number
string
required
The phone number of the device in international format.

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

Example response:

503 Service Unavailable
{
  "error": true,
  "code": 50300,
  "message": "service unavailable"
}

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 a New Phone Number for an 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.

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

Example response:

503 Service Unavailable
{
  "error": true,
  "code": 50300,
  "message": "service unavailable"
}

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",
    "activation_code": "BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8"
}
user_id
OR
username

string
required
ID of the user.
OR
Username, as specified by your application or generated randomly by Futurae.
activation_code
string
required
The activation code is the value of the "activation_code" query parameter which is part of the activation_code_uri field contained in the response of Enroll Users and Devices. Alternatively, you can use as input the whole activation_code_uri value without the futurae:// prefix, as illustrated in the examples below.
Examples:
BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8
OR
enroll?activation_code=BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8

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

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.
Maximum length: 60 characters.
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.

Response 503

Example response:

503 Service Unavailable
{
  "error": true,
  "code": 50300,
  "message": "service unavailable"
}

The action was send, but Futurae was not able to send the SMS, because the SMS service is temporarily unavailable.

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",
        "soundproof",
        "soundproof_jingle"
    ],
    "devices": [
        {
            "device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd",
            "display_name": "My iphone X",
            "capabilities": [
                    "approve",
                    "qr_code",
                    "mobile_totp",
                    "qr_code",
                    "soundproof",
                    "soundproof_jingle"
            ],
            "type": "ios",
            "version": "1.0.1",
            "version_supported": true
        }
    ]
}

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.

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", "soundproof", "soundproof_jingle", "approve", "passcode"],
    "status": "enabled",
    "username": "newusername@domain.com",
    "display_name": "Cooler display name"
}
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.

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"
}
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, the display name is the device model for Futurae mobile app devices (or the phone number for SMS devices).

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.

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

200 OK
{
    "result": "auth",
    "allowed_factors" : [
        "approve",
        "mobile_totp",
        "passcode",
        "soundproof"
    ],
    "devices": [
        {
            "device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd",
            "display_name": "My iphone X",
            "capabilities": [
                    "approve",
                    "qr_code",
                    "mobile_totp",
                    "qr_code",
                    "soundproof",
                    "soundproof_jingle"
            ],
            "type": "ios",
            "version": "1.0.1",
            "version_supported": true
        }
    ],
    "recommended_factor": "soundproof"
}

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.

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

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.

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 Zero-Touch

POST /srv/auth/v1/user/auth

Perform SoundProof (Zero-Touch) authentication for a particular user.

SoundProof can typically be combined with push notification approval (One-Touch) as an automatic fallback in case SoundProof fails. Read on for more details.

Body Parameters

Example request body params:

{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "factor": "soundproof",
    "device_id": "auto",
    "approve_combo": true,
    "new_device_must_approve": 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",
    "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 soundproof.
device_id
string
required
The ID of the device to use. The device must support the soundproof capability (see Device Capabilities). Alternatively, you can specify auto, in which case the most recently enrolled of the user’s devices with the soundproof capability will be used.
approve_combo
boolean
optional
Combine SoundProof with the approve (One-Touch) factor. This can be very useful and recommended for the following reason:
If SoundProof fails, e.g., due to poor recording conditions, then having already activated the approve method by sending the approval notification on the user device, can speed up the login process. In this case, the approve method serves as an automatic fallback mechanism, assuming that the phone is connected to the Internet. If not, then of course neither soundproof nor approve can be used and another fallback mechanism, that does not require internet connectivity will have to be used, such as Authenticate with Passcode.
If not specified, then approve_combo is assumed to be true (i.e., enabled by default).
Default: true
new_device_must_approve
boolean
optional
If the user is logging in from a new device, then do not authenticate with SoundProof and instead fallback directly to approve (One-Touch) authentication which requires explicit user involvement. Once approve authentication succeeds, the user can subsequently login using SoundProof.Default: true
extra_info
[object]
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.
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 and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.
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 means that the token never expires. Applicable only when set_trusted is true.
Default: 30

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 supplied to the client (for example, the user's browser) on which the authentication attempt is taking place, in order to be able to connect to the Futurae server successfully, during the SoundProof execution.

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, or the specified device_id does not support the corresponding capability in order to perform authentication using the chosen factor, or there was no device found that supports the capability needed for the chosen factor.

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 Zero-Touch Jingle

POST /srv/auth/v1/user/auth

Perform SoundProof Jingle (Zero-Touch Jingle) authentication for a particular user.

SoundProof Jingle can typically be combined with push notification approval (One-Touch) as an automatic fallback in case SoundProof Jingle fails. Read on for more details.

Body Parameters

Example request body params:

{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "factor": "soundproof_jingle",
    "device_id": "auto",
    "approve_combo": true,
    "playback_offset": 0,
    "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"
}
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 soundproof_jingle.
device_id
string
required
The ID of the device to use. The device must support the soundproof_jingle capability (see Device Capabilities). Alternatively, you can specify auto, in which case the most recently enrolled of the user’s devices with the soundproof_jingle capability will be used.
approve_combo
boolean
optional
Combine SoundProof Jingle with the approve (One-Touch) factor. This can be very useful and recommended for the following reason:
If SoundProof Jingle fails, e.g., due to poor recording conditions, then having already activated the approve method by sending the approval notification on the user device, can speed up the login process. In this case, the approve method serves as an automatic fallback mechanism.
Default: true
playback_offset
number
optional
Time in milliseconds defining the interval between the time when the jingle is downloaded and the time when the jingle starts being played. The jingle can be retrieved via the jingle_url attribute in the response of this call (see further below). Depending on the use case, for example, in conversational interfaces, it is typically the case that the jingle is retrieved but actually played a few seconds later. For SoundProof Jingle to work properly it is important to specify this time interval using this parameter.An approximate value should suffice.
Minimum: 0
Maximum: 12000 (12 seconds)
Default: 0
extra_info
[object]
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.
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 and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.

Response 200

Example response:

200 OK
{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673",
  "jingle_url": "https://api.futurae.com/usr/v1/audio/jingle?session_token=qQNlDg7mN2kdjlvk5HsFkLWzdJkHFPvqiTsAg5T"
}

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.
jingle_url
string
The URL from which the jingle for this particular authentication session can be retrieved. If the jingle is to be played wit some delay after it is retrieved then the playback_offset parameter has to be set accordingly upon calling this endpoint (see above).

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, or the specified device_id does not support the corresponding capability in order to perform authentication using the chosen factor, or there was no device found that supports the capability needed for the chosen factor.

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

Body Parameters

Example request body params:

{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "factor": "approve",
    "device_id": "auto",
    "async": true,
    "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",
    "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 approve.
device_id
string
required
The ID of the device to use. The device must support the approve capability (see Device Capabilities). Alternatively, you can specify auto, in which case the most recently enrolled of the user’s devices with the approve capability will be used.
async
boolean
optional
If this parameter is present and set to false, then this endpoint will run synchronously and return a response when the authentication process has completed.
On the other hand, if the parameter is not supplied or set to true, then 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.
Enabling async and using Query Authentication Status enables your application to retrieve real-time status updates during the authentication session, instead of only being notified of the result after the process has been completed.
Default: true
type
string
optional
This string is displayed in the Futurae mobile app after the word "Approve". The default is “Login”, so the phrase "Approve Login" appears on the approval details screen.
Default: Login
extra_info
[object]
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.
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 and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.
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 means that the token never expires. Applicable only when set_trusted is true.
Default: 30

Response 200

Example response:

200 OK
{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673",
  "mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}

Successful request with async set to true (default option).

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 user is using a single device (mobile only). Refer to the mobile only guide) for more information.

Response 200

Example response:

200 OK
{
    "result": "allow",
    "status": "allow",
    "status_msg": "Authentication succeeded.",
    "trusted_device_token": "ExANyywJKiI7oNCoYE9FnjVbJZW3QlPY2LFxDBx8CXU="
}

Successful request with async set to false. 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.
trusted_device_token
string
optional
This field will be present if the authentication was successful (i.e., result was allow) and Authenticate User or Authenticate Transaction 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, or the specified device_id does not support the corresponding capability in order to perform authentication using the chosen factor, or there was no device found that supports the capability needed for the chosen factor.

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 Passcode

POST /srv/auth/v1/user/auth

Perform authentication based on a user-supplied passcode.

Body Parameters

Example request body params:

{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "factor": "passcode",
    "passcode": "328905",
    "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 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 means that the token never expires. Applicable only when set_trusted is true.
Default: 30

Response 200

Example response:

200 OK
{
    "result": "allow",
    "status": "allow",
    "status_msg": "Authentication succeeded.",
    "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.
trusted_device_token
string
optional
This field will be present if the authentication was successful (i.e., result was allow) and Authenticate User or Authenticate Transaction 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",
    "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 qr_code.
extra_info
[object]
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.
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 and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.
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 means that the token never expires. Applicable only when set_trusted is true.
Default: 30

Response 200

Example response:

200 OK
{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673",
  "qrcode_url": "https://futurae.com/qr?auth=BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8",
  "mobile_auth_uri": "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).
mobile_auth_uri
string
A URI which can be used for performing authentication when the user is using a single device (mobile only). Refer to the mobile only guide) for more information.

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, or the specified device_id does not support the corresponding capability in order to perform authentication using the chosen factor, or there was no device found that supports the capability needed for the chosen factor.

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 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",
    "status_callback_url": "https://www.domain.com/authcallback?token=alongrandomstringforextrasecurity",
    "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.
Maximum length: 60 characters.
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)
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 and is conditionally returned by this endpoint (see response below). See Query Authentication Status for the description of the rest of the fields.
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 means that the token never expires. 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"
}

Invalid or missing parameters. For example, the specified user_id does not exist, or the specified device_id does not support the corresponding capability in order to perform authentication using the chosen factor, or there was no device found that supports the capability needed for the chosen factor.

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 503

Example response:

503 Service Unavailable
{
    "error": true,
    "code": 50300,
    "message": "service unavailable"
}

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.

Body Parameters

Example request body params:

{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "factor": "approve",
    "device_id": "auto",
    "async": true,
    "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"
}
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). Alternatively, you can specify auto, in which case the most recently enrolled of the user’s devices with the approve capability will be used.
async
boolean
optional
If this parameter is present and set to false, then this endpoint will run synchronously and return a response when the transaction authentication process has completed.
On the other hand, if the parameter is not supplied or set to true, then 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.
Enabling async and using Query Authentication Status enables your application to retrieve real-time status updates during the authentication session, instead of only being notified of the result after the process has been completed.
Default: true
type
string
optional
This string is displayed in the Futurae mobile app after the word "Approve". The default is "Transaction", so the phrase "Approve Transaction" appears on the approval details screen.
Default: Transaction
extra_info
[object]
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.
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 and status_msg. 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.

Response 200

Example response:

200 OK
{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673",
  "mobile_auth_uri": "futurae://auth?session_token=0JxEUTxe8gTvkzrjx-Za9HkdD4sx8CP3ipXzR70iIIV4="
}

Successful request with async set to true (default option).

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 user is using a single device (mobile only). Refer to the mobile only guide) for more information.

Response 200

Example response:

200 OK
{
    "result": "allow",
    "status": "allow",
    "status_msg": "Authentication succeeded."
}

Successful request with async set to false. 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.
trusted_device_token
string
optional
This field will be present if the authentication was successful (i.e., result was allow) and Authenticate User or Authenticate Transaction 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, or the specified device_id does not support the corresponding capability in order to perform authentication using the chosen factor, or there was no device found that supports the capability needed for the chosen factor.

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"
}
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
[object]
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.
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 and status_msg. 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.

Response 200

Example response:

200 OK
{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673",
  "qrcode_url": "https://futurae.com/qr?auth=BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8",
  "mobile_auth_uri": "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 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).
mobile_auth_uri
string
A URI which can be used for performing transaction authentication when the user is using a single device (mobile only). Refer to the mobile only guide) for more information.

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, or the specified device_id does not support the corresponding capability in order to perform authentication using the chosen factor, or there was no device found that supports the capability needed for the chosen factor.

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.

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). 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.",
    "trusted_device_token": "ExANyywJKiI7oNCoYE9FnjVbJZW3QlPY2LFxDBx8CXU="
}

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.
trusted_device_token
string
optional
This field will be present if the authentication was successful (i.e., result was allow) and Authenticate User or Authenticate Transaction 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 use 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: 1800 (30 minute)
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.

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_failed An error occurred while sending the push notification to the user’s device. The user should retrieve the approval request manually by opening the Futurae mobile app.
The Authentication Result will be waiting.
ready_to_record The device has woken up and is ready to start executing recording as part of the SoundProof (Zero-Touch) authentication.
The Authentication Result will be waiting.
soundproof_in_progress The SoundProof (Zero-Touch) protocol is being executed.
The Authentication Result will be waiting.
soundproof_jingle_in_progress The SoundProof Jingle (Zero-Touch Jingle) protocol is being executed.
The Authentication Result will be waiting.
soundproof_retrying SoundProof (Zero-Touch) failed to verify proximity of the two devices, automatically retrying.
The Authentication Result will be waiting.
soundproof_failed This authentication session is running SoundProof (Zero-Touch) with approve_combo on, and SoundProof failed to verify proximity of the two devices, so the user has to approve the login from the app. In other words, authentication is not over yet, it just automatically fell back to Approve (One-Touch). One of the reasons that SoundProof might fail is that the new_device_must_approve option was true, and the user is currently logging in from a new device. In this case, the JavaScript onNewDeviceMustApprove callback will be called, in order to allow the client-side part of your application to display an appropriate message to the user. For all other reasons for which SoundProof failed (e.g., the recordings didn't match) the JavaScript onSoundProofFailed callback will be called instead. Refer to the Zero-Touch (SoundProof) JS guide for more details on these as well as other available callbacks on the client-side.
The Authentication Result will be waiting.
soundproof_jingle_failed This authentication session is running SoundProof (Zero-Touch) Jingle with approve_combo on, and SoundProof failed to verify proximity of the two devices, so the user has to approve the login from the app. In other words, authentication is not over yet, it just automatically fell back to Approve (One-Touch).
The Authentication Result will be waiting.
retry_fallback SoundProof (Zero-Touch) authentication failed and reached max consecutive failed attempts. Retry using another factor.
The Authentication Result will be deny.
timeout_retry Authentication failed due to a timeout. The soundproof, 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.
device_unreachable The device could not be reached remotely within a reasonable amount of time (a few seconds) in order to run the SoundProof (Zero-Touch) protocol, so the operation timed out. The user should retry with the same or other factor.
The Authentication Result will be deny.

This is similar to "timeout_retry", but used only for the case when the push notification that was sent to wake up the Futurae mobile app was not delivered within a reasonable time. This may be an indication that the user's phone does not currently have network connectivity. Hence, a recommended approach is to fallback to "mobile_totp" by asking the user to open the mobile app and transfer the currently displayed code.
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.
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, soundproof, soundproof_jingle 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).
mobile_auth Single device authentication, i.e., when logging in from a device on which the Futurae mobile app is installed and enrolled for this particular user. Refer to the respective Auth API guide section for more information.
mobile_totp Generate time-based one-time codes from within the Futurae mobile app on the user 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).
soundproof SoundProof authentication (aka Zero-Touch), based on comparison of background ambient sounds and inaudible, near-ultrasound pattern emission.
soundproof_jingle SoundProof authentication, based on jingle emission (aka Zero-Touch Jingle).

Device

This resource represents a user device. There are two 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",
            "soundproof",
            "soundproof_jingle"
    ],
    "type": "ios",
    "version": "1.0.1",
    "version_supported": true
}

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 is the device model (or the phone number for SMS devices).
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
Either android or ios. This field is only applicable for Futurae mobile app devices.
version
string
optional
The currently installed Futurae mobile app version. This field is only applicable for Futurae 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 Futurae mobile app devices.
number
string
optional
The phone number of the device. This field is only applicable for SMS devices.

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).
mobile_totp The device can generate time-based one-time codes from within the Futurae mobile app.
qr_code The device supports authentication based on QR code scanning.
sms The device can receive SMS one-time codes.
soundproof The device can be used with SoundProof authentication (aka Zero-Touch).
soundproof_jingle The device can be used with Soundproof jingle-based authentication (aka Zero-Touch Jingle).

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 2019 Futurae Technologies AG.