Back to top

Futurae Auth API Reference

Version 1.0.7

The Futurae Auth API can be used in order to add two-factor authentication and transaction signing to your website or application, 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 Guideline.

Version History (change log)

Getting Started

In order to be able to use the Auth API you will need to get your Service ID, Service 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 contact our servers, and not hardcoded IP addresses as these are subject to change over time.

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

Each request must contain a “Date” header, containing the current time formatted as RFC 2822 and an “Authorization” header (see below on how to construct the “Authorization” header in order to authenticate each request).

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

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

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

Input Field Restrictions

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

  • username (maximum length: 50 characters): Can be either an <e-mail>, or a string with no spaces and with case-sensitive letters, numbers, or the characters . _ - =

  • display_name (maximum length: 50 characters): Can be either an <e-mail>, or a string with spaces and with case-sensitive letters, numbers, or the characters . _ - =

The <e-mail> format, is defined as local@domain, where

  • local, a combination of case-sensitive letters, numbers and the characters . _ + - \# $

  • domain, a combination of case-sensitive _letters, _numbers and the characters . -, followed by a dot and a case-sensitive letter string of 2 to 4 characters

Request Authentication

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

  • The HTTP username will be your Service ID.

  • The HTTP password will be a hex-formatted HMAC-SHA256 signature, computed over the request content in the way described below, using the Service Auth API key as the HMAC key.

  • The HTTP username and password are concatenated using a colon, and the concatenated string is Base64 encoded.

In summary, the “Authorization” header is constructed as follows:

Authorization: Basic base64(Service_ID:hex(hmac(Service_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’):

Component Description
date The current time, formatted as RFC 2822 (essentially the content of the “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 Service Auth API key as the HMAC key. The signature needs to be in hexadecimal ASCII format (i.e., not raw binary). Below there are some code snippets in various languages that demonstrate how to compute the HMAC signature.

import base64, email, hmac, json, hashlib

def sign(method, host, path, params, sid, skey):
    """
    Return HTTP Basic Authentication ("Authorization" and "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: Service 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 {'Date': now, 'Authorization': 'Basic %s' % base64.b64encode(auth)}
require 'base64'
require 'openssl'
require 'time'

# Return HTTP Basic Authentication ("Authorization" and "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+ - Service 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}")

  { '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 Service Auth API key and returns HTTP
// Basic Authentication ("Authorization" and "Date") headers.
func (req *Request) Sign(serviceID, serviceKey string) map[string]string {
    params := req.Params
    if params == "" {
        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{
        "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 "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 Service 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("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 "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 Service 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("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));
        }
    }
}
<?php
/*
 * Return HTTP Basic Authentication ("Authorization" and "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 : Service Auth API key
 *
 * return : array : "Authorization" and "Date" headers
 */
function requestHeaders($method, $host, $path, $params, $serviceID, $skey) {
  $params = $params ? $params : "\n";
  $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),
               "Date: " . $date);
}
?>
var CryptoJS = require("crypto-js");

/**
 * Return HTTP Basic Authentication ("Authorization" and "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 Service 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, "Date": date};
};

This is how a full request might look like:

POST /srv/auth/v1/user/enroll HTTP/1.1
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 Service Auth API key as part of the request, rather only use it as an HMAC key to sign the request content.

You can use the /server/test endpoint 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 working with our test/pilot environment, whenever the request authentication fails, the Futurae server will include detailed error information in its response, in order to help you identify the cause of the failure.

  2. Below, we provide two step-by-step examples on authenticating an example request. You can use the exact examples in your code and compare all the intermediate outputs with the ones below, in order to identify potential issues.

Example 1: GET Request

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

GET https://api-pilot.futurae.com/srv/auth/v1/server/test?testparam=testvalue

Also, suppose that we have the following Service credentials:

  • Service ID: 5f21ab85-af2f-11e7-9c0d-784f43834446

  • Service Auth API key: GhYZvjGJVyBgeSXVMyUD5G4YR7Y2PzutGhp/MwUt

And that the date is:

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

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

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

And represented as a byte sequence:

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

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

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

910ef81f5fcf092d203e77ead93a3896092e4953c9cbb41c3e792e8d0b417168

Then we concatenate this together with the Service ID:

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

And encode in base64:

NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjkxMGVmODFmNWZjZjA5MmQyMDNlNzdlYWQ5M2EzODk2MDkyZTQ5NTNjOWNiYjQxYzNlNzkyZThkMGI0MTcxNjg=

Finally, the resulting request will be:

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

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

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

with body:

{"testparam":"testvalue"}

Also, suppose that we have the following Service credentials:

  • Service ID: 5f21ab85-af2f-11e7-9c0d-784f43834446

  • Service Auth API key: GhYZvjGJVyBgeSXVMyUD5G4YR7Y2PzutGhp/MwUt

And that the date is:

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

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

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

And represented as a byte sequence:

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

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

7132afde8b6a3ec25ac3f56ec62c633bde998379688547942248c431d8019b43

Then we concatenate this together with the Service ID:

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

And encode in base64:

NWYyMWFiODUtYWYyZi0xMWU3LTljMGQtNzg0ZjQzODM0NDQ2OjcxMzJhZmRlOGI2YTNlYzI1YWMzZjU2ZWM2MmM2MzNiZGU5OTgzNzk2ODg1NDc5NDIyNDhjNDMxZDgwMTliNDM=

Finally, the resulting request will be:

POST /srv/auth/v1/server/test HTTP/1.1
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 keys. 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.

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 key, whose value will be true. Moreover, the response will contain an integer code, and a message key that further describes the failure. A detail key may be present if additional information is available. Example:

{
    "error":true,
    "code":40000,
    "message":"Bad request"
}

The HTTP response code will be the first three digits of the more specific code found inside the JSON object.

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

Ping the server
GET/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.

Example URI

GET https://xxxxxx.futurae.com/srv/auth/v1/server/ping

Response  200

Request was successful.

Response Content

KeyDescription
time

UNIX epoch time in milliseconds.

Example Response

{
    "time": 1461694259294
}

api_version

Get API version
GET/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.

Example URI

GET https://xxxxxx.futurae.com/srv/auth/v1/server/api_version

Response  200

Request was successful.

Response Content

KeyDescription
api_version

Futurae Auth API version that this server runs.

Example Response

{
    "api_version": "1.0.0"
}

test

Test authorization
GET/server/test

This endpoint can be called in order to verify that the request authorization is properly implemented and working as expected. For the purposes of testing, you can optionally add dummy URL query parameters.

Example URI

GET https://xxxxxx.futurae.com/srv/auth/v1/server/test

Response  200

Request was successful.

Response Content

KeyDescription
time

UNIX epoch time in milliseconds.

Example Response

{
    "time": 1461694259294
}

Response  401

Authorization failure.

Example Response

{
    "error": true,
    "message": "Authorization data missing or invalid"
}

Test authorization
POST/server/test

This endpoint can be called in order to verify that the request authorization is properly implemented and working as expected. For the purposes of testing, you can optionally add dummy, JSON-formatted, body parameters.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/server/test

Response  200

Request was successful.

Response Content

KeyDescription
time

UNIX epoch time in milliseconds.

Example Response

{
    "time": 1461694259294
}

Response  401

Authorization failure.

Example Response

{
    "error": true,
    "message": "Authorization data missing or invalid"
}

Service

Endpoints related to Service configuration and utilities.

mobile_auth/app_ids

Retrieve allowed App ID patterns
GET/service/mobile_auth/app_ids

This endpoint is only relevant for performing authentication from mobile devices where the Futurae app is installed and enrolled for a particular user (MobileAuth factor). It allows you to retrieve the currently allowed set of App ID patterns. For an explanation of the App ID concept refer to the respective Auth API Guideline section.

Example URI

GET https://xxxxxx.futurae.com/srv/auth/v1/service/mobile_auth/app_ids

Response  200

Request was successful.

Response Content

KeyDescription
app_ids

A list of the currently allowed App ID patterns.

Example Response

{
    "app_ids": ["com.democlient.*", "ch.democlient.demo"]
}

Store a new set of allowed App ID patterns
POST/service/mobile_auth/app_ids

This endpoint is only relevant for performing authentication from mobile devices where the Futurae app is installed and enrolled for a particular user (MobileAuth factor). It allows you to define a new set of allowed App ID patterns. For an explanation of the App ID concept refer to the respective Auth API Guideline section.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/service/mobile_auth/app_ids

Request Body Parameters

ParameterTypeRequiredDescription
app_ids [string]required

List with new App ID patterns.

Example: ["com.democlient.*", "ch.democlient.demo"]

Response  200

Request was successful.

Response Content

KeyDescription
result

“ok”

app_ids

The list of the newly stored App ID patterns.

Example Response

{
    "result": "ok",
    "app_ids": ["com.democlient.*", "ch.democlient.demo"]
}

Response  400

Missing parameters.

Response  406

One or more of the supplied patterns is invalid.

Response Content

KeyDescription
error

true

result

“pattern”

pattern

The first pattern that was found to be invalid.

Example Response

{
    "error": true,
    "result": "pattern",
    "pattern": "com.democlient.[-1]"
}

mobile_auth/service_urls

Retrieve allowed Service URL patterns
GET/service/mobile_auth/service_urls

This endpoint is only relevant for performing authentication from mobile devices where the Futurae app is installed and enrolled for a particular user (MobileAuth factor). It allows you to retrieve the currently allowed set of Service URL patterns. For an explanation of the Service URL concept refer to the respective Auth API Guideline section.

Example URI

GET https://xxxxxx.futurae.com/srv/auth/v1/service/mobile_auth/service_urls

Response  200

Request was successful.

Response Content

KeyDescription
service_urls

A list of the currently allowed Service URL patterns.

Example Response

{
    "service_urls": ["democlient://", "https://service.com/login/", "https://*.service.com/"]
}

Store a new set of allowed Service URL patterns
POST/service/mobile_auth/service_urls

This endpoint is only relevant for performing authentication from mobile devices where the Futurae app is installed and enrolled for a particular user (MobileAuth factor). It allows you to define a new set of allowed Service URL patterns. For an explanation of the Service URL concept refer to the respective Auth API Guideline section.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/service/mobile_auth/service_urls

Request Body Parameters

ParameterTypeRequiredDescription
service_urls [string]required

List with new Service URL patterns.

Example: ["democlient://", "https://service.com/login/", "https://*.service.com/"]

Response  200

Request was successful.

Response Content

KeyDescription
result

“ok”

service_urls

The list of the newly stored Service URL patterns.

Example Response

{
    "result": "ok",
    "service_urls": ["democlient://", "https://service.com/login/", "https://*.service.com/"]
}

Response  400

Missing parameters.

Response  406

One or more of the supplied patterns is invalid.

Response Content

KeyDescription
error

true

result

“pattern”

pattern

The first pattern that was found to be invalid.

Example Response

{
    "error": true,
    "result": "pattern",
    "pattern": "https://[-1]"
}

pending_enrollments

Retrieve pending enrollments
GET/service/pending_enrollments

This endpoint can be used to retrieve information about all the pending enrollments (created via /user/enroll 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.

Example URI

GET https://xxxxxx.futurae.com/srv/auth/v1/service/pending_enrollments?begin=1497188000&end=1497188999&offset=0

Request Query String Parameters

ParameterTypeRequiredDescription
begin numberrequired

Begin of the time range formatted as a UNIX timestamp in seconds.

Example: 1497188000
end numberrequired

End of the time range formatted as a UNIX timestamp in seconds.

Example: 1497188999
offset numberrequired

Offset of first result.

0: return results 0 - 49.

50: return results 50 - 99.

Keep increasing by 50 until no results are returned.

Example: 0

Response  200

Request was successful.

The response is a JSON object containing an array of objects, one for each individual enrollment.

The attributes contained in these objects are identical to the ones returned by /user/enroll, with the addition of a creation attribute 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.

Example Response

{
    "enrollments":[
        {
            "activation_code_uri":"futurae://Tf9T5Cl1ffnkDSiD0AmWizbSxxHABbIsYr3bMn14HYU=",
            "activation_qrcode_url":"https://testsrv.futurae.com:19080/srv/auth/v1/qr?enroll=Tf9T5Cl1ffnkDSiD0AmWizbSxxHABbIsYr3bMn14HYU=",
            "creation":1497188739,
            "expiration":1497275140,
            "user_id":"4176549f-4eac-11e7-88d8-c241ed9b4fdd",
            "username":"2k9XxrwscVlpczOraIQJgfHfJTRLZ19uXNCXlzPh8pg="
        },
        {
            "activation_code_uri":"futurae://JyEBs1p4JyCU6p0GEJ-mhKgaUIw3ny0t4R6FTNRrf10=",
            "activation_qrcode_url":"https://testsrv.futurae.com:19080/srv/auth/v1/qr?enroll=JyEBs1p4JyCU6p0GEJ-mhKgaUIw3ny0t4R6FTNRrf10=",
            "creation":1497188791,
            "expiration":1497275191,
            "user_id":"6011731c-4eac-11e7-88d8-c241ed9b4fdd",
            "username":"SWJxnclWdGwMr8G1rUxfnL7HCeLJchh-Ckuitsw-m9Q="
        }
    ]
}

Response  400

Invalid or missing parameters.

User

Endpoints related to user enrollment and management.

enroll

Enroll new user or user device
POST/user/enroll

The /user/enroll endpoint provides a programmatic way to enroll new users with Futurae two-factor authentication. There are two distinct enrollment cases, depending on whether you wish to enroll 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 send one-time codes over SMS (“sms” factor in /user/auth):

  • If phone_number is not supplied, /user/enroll creates the user in Futurae and returns an activation code as a QR code image (also as a custom URI) that the Futurae mobile app can scan using the mobile’s built-in camera. Scanning the QR code adds the user’s account to the app and associates that particular device with the user’s account, to be used as the second authentication factor.

  • If phone_number is supplied, /user/enroll creates the user in Futurae and registers a new phone number that can be associated with the user in order to send SMS one-time codes. Note that the phone number has to be verified before being able to send SMS one-time codes with /user/auth. This can be done with /user/sms_activation.

This endpoint also serves as a way to programmatically add new devices for an existing user. This can be achieved by supplying an existing user_id parameter in the request (see below).

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/enroll

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringoptional

The permanent, unique ID of the user as generated by Futurae.

Must be supplied when enrolling a new device for an existing user.

Must be omitted when enrolling a new user (Futurae will generate and return a new ID for the new user. See response content below).

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringoptional

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 here for the input restrictions that apply.

Must be omitted when enrolling a new device for an existing user. In other words, it is not permitted to specify both user_id and username parameters at the same time.

Example: someuser@domain.com
display_name stringoptional

An optional display name, which is displayed on the user’s Futurae mobile app. As an example, it could be the user’s username. See here for the input restrictions that apply.

Must be omitted when enrolling a new device for an existing user. In other words, it is not permitted to specify both user_id and display_name parameters at the same time.

Example: someuser@domain.com
valid_secs numberoptional

Time, in seconds, for which the activation code will remain valid.

Only applicable when enrolling a device for Futurae mobile app-based two-factor authentication (i.e., the phone_number parameter is not supplied).

Minimum: 60

Maximum: 7776000 (90 days)

Default: 604800 (7 days) 
success_callback_url stringoptional

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 /user/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 keys and corresponding values: user_id, username, activation_code 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.

Only applicable when enrolling a device for Futurae mobile app-based two-factor authentication (i.e., the phone_number parameter is not supplied).

phone_number stringoptional

The phone number of the device. This is only applicable when enrolling a user’s phone for sending SMS one-time codes (“sms” factor in /user/auth).

Example: +41123456789

Response  200

Request was successful and phone_number was not supplied.

Response Content

KeyDescription
activation_qrcode_url

URL for an image of a scannable QR code with the activation code. This is useful when the user attempts to enable two-factor authentication by accessing his account from a device different than the one which will be enrolled as a second factor, e.g., when accessing his account from a desktop/laptop computer.

activation_code_uri

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 two-factor authentication directly from the device that will be enrolled as his second factor device (e.g., the URI can be sent via email to be opened directly on the second factor device where the Futurae mobile app is installed and about to be enrolled).

expiration

Time at which this activation code will expire. Formatted as a UNIX timestamp (in seconds).

user_id

Permanent, unique identifier for the user in Futurae. Always generated.

username

Unique name for the user in Futurae. Either specified as a parameter or auto-generated.

Example Response

{
  "activation_qrcode_url": "https://futurae.com/qr?enroll=BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8",
  "activation_code_uri": "futurae://BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8",
  "expiration": 1461694259,
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "username": "someuser@domain.com"
}

Response  200

Request was successful and phone_number was supplied.

Response Content

KeyDescription
device_id

Device ID of the newly created device that has the SMS capability. Use the supplied device ID with /user/sms_activation in order to verify the phone number and make it eligible for use as second factor.

user_id

Permanent, unique identifier for the user in Futurae. Always generated.

username

Unique name for the user in Futurae. Either specified as a parameter or auto-generated.

Example Response

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

Response  400

Invalid or missing parameters, or the supplied user_id does not exist, or a user with username already exists.

In particular, if the supplied phone_number is invalid, the code key within the JSON response will have the value “40001”. The response in such a case is shown in the example below.

Example Response

{
    "error":true,
    "code":40001,
    "message":"invalid phone number"
}

enroll_status

Check user mobile app enrollment status
POST/user/enroll_status

Check whether a user has completed enrollment. Only applicable with Futurae mobile app-based enrollment (i.e., when /user/enroll is called without a phone_number parameter). Note that the endpoint returns immediately with the current enrollment status, thus you would need to use this endpoint on 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.

Note: An alternative way of getting notified upon when an enrollment completes successfully is to supply the success_callback_url in /user/enroll. Both ways (i.e., this endpoint and the callback URL) can be used in parallel if needed.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/enroll_status

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
activation_code stringrequired

Activation code, as returned from /user/enroll (in particular the value of activation_code_uri without the “futurae://” prefix).

Example: BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8

Response  200

Request was successful.

Response Content

KeyDescription
result

Status of the enrollment. It can have one of the following values:

ValueDescription
"success"

The user successfully enrolled with a new device.

"expired"

The code expired.

"pending"

The code has not been claimed yet.

device_id

Only applicable if result is “success”. The device ID of the device that got enrolled with the specified activation_code.

In all other cases it will be an empty string.

Example Response

{
    "result": "success",
    "device_id": "5bde7d1f-206b-4857-877d-f314912b83f0"
}

Response  400

Invalid or missing parameters, or the specified user_id and activation_code combination does not exist.

sms_activation

Send or verify SMS activation codes
POST/user/sms_activation

Verify a newly registered phone number (through /user/enroll). 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 secondary authentication (for example in case the SMS does not arrive, you can retry sending another SMS).

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/sms_activation

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
device_id stringrequired

The device ID, as returned from /user/enroll.

Example: BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8
action stringrequired

If set to “send” then the Futurae server will send an activation code over SMS to the registered phone number (as supplied in /user/enroll). Your application needs to subsequently call this endpoint once again with a different action (see next paragraph) in order to verify the passcode supplied by the user. The activation code will have an expiration time of 5 minutes.

If set to “verify” then Futurae will check if the user supplied passcode matches the one sent over SMS to the user’s phone.

Choices: send verify

sms_text stringoptional

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 is 60 characters.

Only applicable if action is “send”.

passcode stringrequired

if  action is “verify”

The user supplied passcode that needs to be verified.

Only applicable if action is “verify”.

Response  200

Request was successful.

Response Content

KeyDescription
result

The result of calling the endpoint. It can have one of the following values:

ValueDescription
"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 secondary 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 enpoint 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.

Example Response

{
    "result": "sent"
}

Response  400

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. Morever, the supplied phone number might be wrongly formatted, making it impossible to send the verification SMS.

Response  503

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

users

Lookup users
GET/users

Lookup up a user based on various filters [Currently only lookup by username is supported.]

Example URI

GET https://xxxxxx.futurae.com/srv/auth/v1/users?username=someuser%40domain.com

Request Query String Parameters

ParameterTypeRequiredDescription
username stringrequired

Lookup the user that has the supplied username.

Example: someuser@domain.com

Response  200

Request was successful.

Response Content

KeyDescription
user_id

The permanent, unique identifier of the user in Futurae.

username

The username of this user (which was either specified by your application or generated randomly by Futurae).

status

The user’s status. It will be one of the following values:

ValueDescription
"bypass"

The user can bypass secondary authentication, i.e., only primary authentication is used for authenticating the user.

"enabled"

The user has one or more enrolled devices and must complete secondary authentication using one of them.

"disabled"

The user has no enrolled devices and secondary authentication is disabled. The user cannot authenticate using secondary authentication, before he enrolls a device.

"locked_out"

The user has been locked out due to an excessive amount of failed authentication attempts. His status needs to be reset (via POST /users/{id}) in order to be able to authenticate again.

Example Response

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

Response  400

Invalid or missing parameters, or the specified username does not exist.

users

Retrieve user status
GET/users/{id}

Get information about the status and the enrolled devices of the user with ID id.

Example URI

GET https://xxxxxx.futurae.com/srv/auth/v1/users/7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6

Response  200

Request was successful.

Response Content

KeyDescription
username

The username of this user (which was either specified by your application or generated randomly by Futurae).

display_name

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

The user’s status. It will be one of the following values:

ValueDescription
"bypass"

The user can bypass secondary authentication, i.e., only primary authentication is used for authenticating the user.

"enabled"

The user has one or more enrolled devices and must complete secondary authentication using one of them.

"disabled"

The user has no enrolled devices and secondary authentication is disabled. The user cannot authenticate using secondary authentication, before he enrolls a device.

"locked_out"

The user has been locked out due to an excessive amount of failed authentication attempts. His status needs to be reset (via POST /users/{id}) in order to be able to authenticate again.

devices

(If status is “disabled”, this field will not be present.) A list of the user’s devices and their capabilities.

Refer to /user/preauth for a description of the format of this field.

allowed_factors

(If status is “disabled”, this field will not be present.) A list of the authentication factors that are permitted to be used for this user. One or more of the following factors will be contained in the list:

ValueDescription
"approve"

Authentication based on approvals received through push notifications.

"mobile_auth"

Perform MobileAuth, a seamless, strong authentication technique for 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 Guideline section for more information.)

"mobile_totp"

Generate time-based one-time codes from within the Futurae mobile app on the user device.

"passcode"

A one-time code which can be obtained via the /user/one_time_code endpoint, sent to the user by some means (handled by your application) and then the user-submitted code can be verified by calling /user/auth. Always allowed, will always be present in the list.

"qr_code"

Authentication based on QR code scanning.

"sms"

Receive SMS one-time codes.

"soundproof"

SoundProof authentication.

Example Response

{
    "username": "someone@domain.com",
    "display_name": "someone",
    "status": "enabled",
    "devices": [
        {
            "device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
            "capabilities": [
                    "soundproof",
                    "approve",
                    "qr_code",
                    "mobile_totp"
            ],
            "number": ""
        }
    ],
    "allowed_factors" : [
        "approve",
        "mobile_totp",
        "passcode",
        "soundproof",
    ]
}

Response  400

Invalid or missing parameters, or the specified user id does not exist.

Modify user
POST/users/{id}

Modify attributes of the user with ID id.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/users/7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6

Request Body Parameters

ParameterTypeRequiredDescription
allowed_factors [string]optional

A list of strings, containing the factors that are allowed to be used for secondary authentication for this user. 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.

Refer to GET /users/{id} for a description of the available factors.

Note that the passcode factor, whereby a one-time code can be obtained via the /user/one_time_code endpoint, sent to the user by some means and then send the user-submitted code for verification using /user/auth, is always allowed and available for use.

Since passcode is always allowed, it does not have to be explicitly set in the supplied list of factors. Moreover, if the supplied list is empty, it means that passcode will be the only available factor.

Example: ["soundproof", "approve", "mobile_totp"]
status stringoptional

Setting to “enabled” will remove the “bypass” status, meaning that the user will have to authenticate using secondary authentication. It will also reset the user to be able to authenticate again, in case he was locked out due to an excessive amount of failed authentication attempts. Note, however, that if the user has no enrolled devices, his status will become “disabled”, as he still needs to enroll a new device in order to become enabled to perform secondary authentication.

Setting to “bypass” will allow the user to completely bypass secondary authentication from now on. It will also reset the user to be able to authenticate again, in case he was locked out due to an excessive amount of failed authentication attempts.

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

See also the descriptions of these values in GET /users/{id}.

Choices: enabled bypass disabled

Example: enabled
username stringoptional

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 here for the input restrictions that apply.

Example: newusername@domain.com
display_name stringoptional

Set a new display name for this user (displayed on the user’s Futurae mobile app). As an example, it could be the user’s username. See here for the input restrictions that apply.

Example: newusername@domain.com

Response  200

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.

Example Response

{
    "username": "newusername@domain.com",
    "status": "bypass"
}

Response  400

Invalid parameters, or the specified user id does not exist, or the specified username already exists.

unenroll

Unenroll user device
POST/user/unenroll

Unenroll (deactivate) a device of a user. If the specified device is the only enrolled device for the user, then two-factor authentication will automatically be disabled for this user. The user will have to enroll a device again in order to be able to authenticate using secondary authentication.

This endpoint should only be called if there is no current authentication attempt taking place for that particular user using that device. Otherwise, the result is undefined.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/unenroll

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
device_id stringrequired

ID of the device that will be unenrolled.

Example: 5bde7d1f-206b-4857-877d-f314912b83f0

Response  200

Request was successful.

Response Content

KeyDescription
result

Describes the result of the device unenrollment. It can have one of the following values:

ValueDescription
"success"

The specified device was successfully unenrolled.

"success_2fa_disabled"

The specified device was successfully unenrolled. This was the only enrolled device for the user, therefore two-factor authentication was automatically disabled for that user.

Example Response

{
    "result": "success"
}

Response  400

Invalid or missing parameters, or the particular user_id and device_id combination does not exist, or the specified device_id is already unenrolled.

backup_codes

Generate a list of backup codes
POST/user/backup_codes

Clear the entire existing list of backup authentication codes and generate a new one. The codes are numerical (only digits) and generated randomly. The user should store the backup codes safely and use them to authenticate in case he has lost access to his devices.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/backup_codes

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
count numberoptional

How many codes to generate.

Minimum: 1

Maximum: 10

Default: 10 
length numberoptional

How long (number of digits) each code should be.

Minimum: 8

Maximum: 20

Default: 10 
reuse_count numberoptional

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

Request was successful.

Response Content

KeyDescription
backup_codes

The newly generated backup codes, formatted with some spacing to make them more readable.

Example Response

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

Response  400

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

devices

Modify user device
POST/user/devices/{id}

Modify a user device with ID id.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/devices/70982f83-4543-11e7-89ab-c241ed9b4fdd

Request Body Parameters

ParameterTypeRequiredDescription
display_name stringoptional

Sets the the display name for that particular device. Useful for when a user has multiple devices enrolled with his account. It can serve as a (usually) user-chosen mnemonic name to help the user choose which device he wishes to use for secondary authentication.

Example: my android phone

Response  200

Request was successful.

Example Response

{
}

Response  400

Invalid or missing parameters, or the specified device id does not exist.

User Authentication

Endpoints related to user authentication procedures.

preauth

User authentication options
POST/user/preauth

Check if the user should perform secondary authentication and if so, return the available authentication factors for this user.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/preauth

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user to be authenticated.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
trusted_device_token stringoptional

If the supplied token is valid, return an “allow” response, meaning that the user does not have to perform secondary authentication as the attempt originates from a trusted device.

Example: ExANyywJKiI7oNCo YE9FnjVbJZW3QlPY2LFxDBx8CXU=

Response  200

Request was successful.

Response Content

KeyDescription
result

One of the following values:

ValueDescription
"auth"

The user is eligible for secondary authentication. Use the /user/auth endpoint to proceed (alternatively, for performing transaction authentication call the /user/auth/transaction endpoint).

"allow"

The user is configured to bypass secondary authentication, or is authenticating from a trusted device (valid supplied trusted_device_token). 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 due to excessive failed authentication attempts, or the user has no enrolled devices and thus two-factor authentication is disabled.

"unknown"

The specified user_id or username is not recognized by Futurae, and as such, secondary authentication does not apply. For new users, or in case the supplied user_id is a remnant of a previously deleted user in Futurae, /user/enroll should be used, before being able to perform secondary authentication for this user.

allowed_factors

A list of the authentication factors that are permitted to be used for this user. Refer to GET /users/{id} for a detailed description of the list content.

devices

A list of the user’s devices, where each device is a series of key/value pairs. This field will only be present if result is “auth”.

KeyDescription
device_id

The ID of this device.

display_name

A short, memorable string which can be used to identify the device in a prompt.

capabilities
ValueDescription
"approve"

The device supports authentication using approvals sent via push notifications.

"mobile_auth"

The device supports MobileAuth (seamless, strong authentication for same-device logins. See the respective Auth API Guideline section for more information.)

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

type

Either “android” or “ios”.

This is only applicable for devices that have the Futurae mobile app installed and enrolled for this user (i.e., not applicable for devices with a registered phone number that offer the “sms” capability).

version

The currently installed Futurae mobile app version.

Similar to previous field, only applicable for Futurae mobile app devices.

version_supported

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 this means that the only functional capability of this device is “mobile_totp” (in this case, the user can be authenticated by calling /user/auth with “passcode” factor and a user-supplied mobile totp). All other factors will not be usable unless the user updates the mobile app.

Similar to previous field, only applicable for Futurae mobile app devices.

number

The phone number of the device.

This field is only applicable for SMS devices, with a registered phone number. A registered phone number is necessary in order for the device to offer the “sms” capability.

recommended_factor

The factor to use for secondary authentication as recommended by Futurae, and based on the capabilities of the user’s devices. This field will only be present if result is “auth”.

Example Response

{
    "result": "auth",
    "devices": [
        {
            "device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
            "capabilities": [
                    "soundproof",
                    "push",
                    "qr_code",
                    "mobile_totp"
            ],
            "number": "",
            "type": "ios",
            "version": "1.0.1",
            "version_supported": true
        }
    ],
    "recommended_factor": "soundproof"
}

Response  400

Invalid or missing parameters.

auth

Perform authentication
POST/user/auth

Perform secondary authentication using one of the available factors. The response of this endpoint depends on the chosen factor. See further below for details.

NOTE: Also see the /user/auth/transaction endpoint, which is tailored for transaction authentication operations.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/auth

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user to be authenticated.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
factor stringrequired

Factor to use for the secondary authentication. The following options are supported:

Value Description
“approve” Use login approval via push notification.
“mobile_auth” Perform MobileAuth authentication from a device on which the Futurae mobile app is installed and enrolled for this user. (For an overview on how to implement MobileAuth see the respective Auth API Guideline section.)
“passcode” Verify user supplied passcode (backup code, one-time code, mobile totp).
“qr_code” Use QR code scanning.
“sms” Send an SMS one-time code to the user (Futurae server sends the SMS).
“soundproof” Use SoundProof. (For an overview on how to implement SoundProof see the respective Auth API Guideline section.)

Also see below for additional factor-specific parameters that may need to be supplied.

set_trusted booleanoptional

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 the /user/preauth endpoint, in order to immediately grant access (without performing secondary authentication), whenever the authentication attempt originates from this device.

trusted_days numberoptional

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. Relevant only when set_trusted is true.

Default: 30 
status_callback_url stringoptional

A URL that Futurae server can call in order to deliver status updates as well as the result of a particular authentication attempt (also called authentication session). It can be used as an alternative to /user/auth_status for receiving status updates about an authentication session. 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 keys and corresponding values: 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 further below). See the /user/auth_status endpoint for an explanation of the rest of the fields.

The supplied URL must be over https. It is very important to keep the session ID secret (i.e., not disclose it to the client-side) to ensure that only the Futurae server will be able to call the URL with the correct session ID. As an alternative callback authentication method, your callback URL should include a sufficiently long random nonce.

This param is only applicable in the cases where this endpoint returns a session_id (see further below).


Depending on the chosen factor, the following additional parameters need to be supplied.

approve

ParameterTypeRequiredDescription
device_id stringrequired

The ID of the device to use. The device must support the “approve” capability. Alternatively, you can specify “auto”, in which case the most recently enrolled of the user’s devices with the “approve” capability will be used.

Example: 5bde7d1f-206b-4857-877d-f314912b83f0
async booleanoptional

If this parameter is present and set to false, then the /user/auth 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 /user/auth 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, via the /user/auth_status endpoint.

Enabling async allows 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 stringoptional

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. Alternatively, you could specify “Transaction”, “Payment” and so forth.

extra_info stringoptional

A set of JSON-formatted key/value pairs, with additional contextual information associated with this authentication attempt. The Futurae app will display this information to the user in the approval details screen.


mobile_auth

ParameterTypeRequiredDescription
device_id stringrequired

The ID of the device to use. This is essentially the mobile device from which the authentication attempt is taking place. The device must support the “mobile_auth” capability. Alternatively, you can specify “auto”, in which case the most recently enrolled of the user’s devices with the “mobile_auth” capability will be used.


passcode

ParameterTypeRequiredDescription
passcode stringrequired

The passcode submitted by the user. It does not matter if the code contains spaces, as they will be automatically removed.

Example: 328905

sms

ParameterTypeRequiredDescription
device_id stringrequired

The ID of the device to send the SMS one-time code to. The device must support the “sms” capability. 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 stringoptional

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 is 60 characters.

Only applicable if action is “send”.

valid_secs numberoptional

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) 

soundproof

Note: SoundProof can typically be combined with push notification approval (i.e., with the “approve” factor). Read the supplied parameters for more details.

ParameterTypeRequiredDescription
device_id stringrequired

The ID of the device to use. The device must support the “soundproof” capability. Alternatively, you can specify “auto”, in which case the most recently enrolled of the user’s devices with the “soundproof” capability will be used.

Example: 5bde7d1f-206b-4857-877d-f314912b83f0
approve_combo booleanoptional

Combine SoundProof with the “approve” factor. This can be very useful and recommended for the following reasons:

  • If the SoundProof factor 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 a 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 “sms” or “passcode”.

  • The notification which is sent by the “approve” factor, can serve as a way of alerting the user when an attacker attempts a fraudulent login on the user’s account.

If not specified, then approve_combo is assumed to be true (i.e., enabled by default).

Default: true 
new_device_must_approve booleanoptional

If the user is logging in from a new device, then do not run SoundProof and instead fallback directly to the “approve” factor. Once the “approve” factor succeeds the user can subsequently login using SoundProof.

If this param is true, it always sets approve_combo to true, as well.

Note: This feature uses localStorage of the Web Storage API in order to store cryptographically protected values that identify a user that has logged in from a particular browser in the past. Calling localStorage.clear() from your site’s JavaScript code will delete these values. Hence a subsequent authentication attempt with new_device_must_approve set to true will force an “approve” factor, even if the user has authenticated from this browser in the past.

Default: true 
extra_info stringoptional

Applicable only when approve_combo is true.

A set of JSON-formatted key/value pairs, with additional contextual information associated with this authentication attempt. The Futurae app will display this information to the user in the approval details screen.

Response  200

Successful request, however the user is locked out, or can bypass two-factor authentication, or has two-factor authentication disabled. In this case the authentication result is immediately returned.

Response Content

KeyDescription
result

Either “allow” or “deny”:

ValueDescription
"allow"

Your application should grant access to the user.

"deny"

Your application should deny access to the user.

status

String detailing the reason of the result. One of:

ValueDescription
"bypass"

The user can bypass secondary authentication. The result will be “allow”.

"disabled"

Two-factor authentication is disabled for this user. The result will be “deny”.

"locked_out"

The user is locked out as authentication has failed too many times, and needs to be reset (via POST /users/{id}) in order to be able to authenticate again. The result will be “deny”.

status_msg

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.

Example Response

{
    "result": "allow",
    "status": "bypass",
    "status_msg": "Login successful"
}

Response  200

Successful request with factor being “approve” and async enabled.

Response Content

KeyDescription
session_id

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 the /user/auth_status endpoint. The session ID must be kept secret (i.e., not disclosed to the client-side).

Example Response

{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673"
}

Response  200

Successful request with factor being “approve” and async disabled, or factor being “passcode”.

Response Content

KeyDescription
result

Either “allow” or “deny”:

ValueDescription
"allow"

Authentication was successful. Your application should grant access to the user.

"deny"

Authentication failed. Your application should deny access. Depending on the status reported in the status field below, it might need to retry the authentication process, possibly with a different fallback factor.

status

String detailing the progress or outcome of the authentication attempt. If the authentication attempt was denied, it may identify a reason. Use the result response to decide whether to grant access or not.

See the /user/auth_status endpoint for more details.

status_msg

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.

trusted_device_token

If the authentication was successful (i.e., result was “allow”) and the set_trusted parameter was set to true, this will be a token that can be used to mark the device from which the authentication attempt took place as trusted. This can later be passed to the /user/preauth endpoint, in order to immediately grant access (without performing secondary authentication), in case the authentication attempt originates from this device.

Example Response

{
    "result": "allow",
    "status": "completed",
    "status_msg": "Login successful",
    "trusted_device_token": "ExANyywJKiI7oNCoYE9FnjVbJZW3QlPY2LFxDBx8CXU="
}

Response  200

Successful request with factor being “qr_code”.

Response Content

KeyDescription
session_id

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 the /user/auth_status endpoint. The session ID must be kept secret (i.e., not disclosed to the client-side).

qrcode_url

The URL from which the QR code 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.

Example Response

{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673",
  "qrcode_url": "https://futurae.com/qr?auth=BSDw42z-tyKVNR7eWLbvlziYg2RlGZrNMH6WDwl8"
}

Response  200

Successful request with factor being “sms”.

Response Content

KeyDescription
result

Always the value “deny”. This indicates that your application has to call /user/auth once again, setting factor to “passcode” and submit the passcode supplied by the user, in order to check its validity.

Example Response

{
  "result": "deny"
}

Response  200

Successful request with factor being “mobile_auth” or “soundproof”.

Response Content

KeyDescription
session_id

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 the /user/auth_status endpoint. The session ID must be kept secret (i.e., not disclosed to the client-side).

session_token

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 authenticate successfully to the Futurae server, during the protocol execution. (For an overview on how to implement SoundProof, or authentication from mobile devices refer to the Auth API Guideline.

Example Response

{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673",
  "session_token": "qQNlDg7mN2kdjlvk5HsFkLWzdJkHFPvqiTsAg5TE"
}

Response  400

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, or the chosen factor is not allowed for this user.

Response  403

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 POST /users/{id}). Your application needs to use another factor to authenticate this user.

Moreover, if factor was SoundProof, it might be the case that the user has failed too many times to authenticate using SoundProof. In this case, the “soundproof” factor cannot be used until the user authenticates using another authentication factor first.

Response  503

The factor was “sms”, but 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.

auth/transaction

Perform transaction authentication
POST/user/auth/transaction

Perform transaction authentication using one of the available factors. This endpoint is similar to /user/auth but tailored for transaction authentication operations. The response of this endpoint depends on the chosen factor. See further below for details.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/auth/transaction

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user to be authenticated.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
factor stringrequired

Factor to use for authenticating the transaction. The following options are supported:

Value Description
“approve” Use transaction approval via push notification.
set_trusted booleanoptional

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 the /user/preauth endpoint, in order to immediately grant access (without performing secondary authentication), whenever the authentication attempt originates from this device.

trusted_days numberoptional

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. Relevant only when set_trusted is true.

Default: 30 
status_callback_url stringoptional

A URL that Futurae server can call in order to deliver status updates as well as the result of a particular transaction authentication attempt (also called authentication session). It can be used as an alternative to /user/auth_status for receiving status updates about a transaction authentication session. 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 keys and corresponding values: 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 further below). See the /user/auth_status endpoint for an explanation of the rest of the fields.

The supplied URL must be over https. It is very important to keep the session ID secret (i.e., not disclose it to the client-side) to ensure that only the Futurae server will be able to call the URL with the correct session ID. As an alternative callback authentication method, your callback URL should include a sufficiently long random nonce.


Depending on the chosen factor, the following additional parameters need to be supplied.

approve

ParameterTypeRequiredDescription
device_id stringrequired

The ID of the device to use. The device must support the “approve” capability. Alternatively, you can specify “auto”, in which case the most recently enrolled of the user’s devices with the “approve” capability will be used.

Example: 5bde7d1f-206b-4857-877d-f314912b83f0
async booleanoptional

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, via the /user/auth_status endpoint.

Enabling async allows 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 stringoptional

This string is displayed in the Futurae mobile app after the word “Approve”. The default is “Transaction”, so the phrase “Approve Login” appears on the approval details screen. Alternatively you could specify “Action”, “Payment” and so forth.

extra_info stringoptional

A set of JSON-formatted key/value pairs, with additional contextual information associated with this transaction authentication attempt. The Futurae app will display this information to the user in the approval details screen.

Response  200

Successful request, however the user is locked out, or can bypass two-factor authentication, or has two-factor authentication disabled. In this case the authentication result is immediately returned.

Response Content

KeyDescription
result

Either “allow” or “deny”:

ValueDescription
"allow"

Your application should grant access to the user.

"deny"

Your application should deny access to the user.

status

String detailing the reason of the result. One of:

ValueDescription
"bypass"

The user can bypass secondary authentication. The result will be “allow”.

"disabled"

Two-factor authentication is disabled for this user. The result will be “deny”.

"locked_out"

The user is locked out as authentication has failed too many times, and needs to be reset (via POST /users/{id}) in order to be able to authenticate again. The result will be “deny”.

status_msg

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.

Example Response

{
    "result": "allow",
    "status": "bypass",
    "status_msg": "Login successful"
}

Response  200

Successful request with factor being “approve” and async enabled.

Response Content

KeyDescription
session_id

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 the /user/auth_status endpoint. The session ID must be kept secret (i.e., not disclosed to the client-side).

Example Response

{
  "session_id": "f18b2152-83d6-4a36-b531-98163042c673"
}

Response  200

Successful request with factor being “approve” and async disabled.

Response Content

KeyDescription
result

Either “allow” or “deny”:

ValueDescription
"allow"

Authentication was successful. Your application should grant access to the user.

"deny"

Authentication failed. Your application should deny access. Depending on the status reported in the status field below, it might need to retry the authentication process, possibly with a different fallback factor.

status

String detailing the progress or outcome of the authentication attempt. If the authentication attempt was denied, it may identify a reason. Use the result response to decide whether to grant access or not.

See the /user/auth_status endpoint for more details.

status_msg

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.

trusted_device_token

If the authentication was successful (i.e., result was “allow”) and the set_trusted parameter was set to true, this will be a token that can be used to mark the device from which the authentication attempt took place as trusted. This can later be passed to the /user/preauth endpoint, in order to immediately grant access (without performing secondary authentication), in case the authentication attempt originates from this device.

Example Response

{
    "result": "allow",
    "status": "completed",
    "status_msg": "Login successful",
    "trusted_device_token": "ExANyywJKiI7oNCoYE9FnjVbJZW3QlPY2LFxDBx8CXU="
}

Response  400

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, or the chosen factor is not allowed for this user.

Response  403

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 POST /users/{id}).

auth_status

Query authentication status
POST/user/auth_status

Your application can use this endpoint to get status updates as well as the result of a particular authentication attempt (also called authentication session). This endpoint can return a response in two different ways:

  • It can wait until the authentication session has been completed and return when the result is available.

  • It can wait just for the next status update during the authentication session and return the new status. It can then be called once again to either retrieve the next status update or wait for the result to become available (depending on how it’s called this time).

Note: An alternative way of receiving status updates about an authentication session is to supply the status_callback_url in /user/auth or /user/auth/transaction. Both ways (i.e., this endpoint and the callback URL) can be used in parallel if needed.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/auth_status

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user to be authenticated.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
session_id stringrequired

The session ID of the authentication attempt as returned by /user/auth or /user/auth/transaction.

Example: f18b2152-83d6-4a36-b531-98163042c673
final_result booleanoptional

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

Request was successful.

Response Content

KeyDescription
result

One of the following values:

ValueDescription
"allow"

Authentication was successful. Your application should grant access to the user.

"deny"

Authentication failed. Your application should deny access. Depending on the status reported in the status field below, it might need to retry the authentication process, possibly with a different fallback factor.

"waiting"

Authentication is still in-progress. Your application should poll again until it finishes. Check the status for more details on the progress.

status

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. status will contain one of the following values.

ValueDescription
"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 result will be “waiting”.

"device_unreachable"

The device has not yet been reached in order to run the SoundProof protocol.

The result will be “waiting”.

Your application can already consider prompting the user to use a fallback factor. In the meantime, if the phone is reached and the login page on the user’s browser that runs SoundProof is still active, then SoundProof will eventually execute and return a result. You application can then log the user in if the result is “allow”, assuming that the user has not already managed to log in using some other factor.

"ready_to_record"

The device has woken up and is ready to start executing the SoundProof recording. Call /user/auth, if you haven not already.

The result will be “waiting”.

"soundproof_in_progress"

The SoundProof protocol (recording and comparison) is being executed.

The result will be “waiting”.

"soundproof_retrying"

Audio comparison failed, automatically retrying.

The result will be “waiting”.

"soundproof_failed"

This authentication session is running SoundProof with approve_combo on, and the SoundProof part just failed, so the user has to approve the login from the app (i.e., authentication is not over yet, it just automatically fell back to Approve). 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 SoundProof JavaScript library for more details on these as well as other available callbacks on the client-side.

The result will be “waiting”.

"mobile_auth_enroll_browser"

As part of executing the “mobile_auth” factor, a new browser is being enrolled (used to log in the first time).

The result will be “waiting”.

"mobile_auth_enroll_app"

As part of executing the “mobile_auth” factor, a new native app is being enrolled (used to log in the first time).

The result will be “waiting”.

"mobile_auth_failed"

The execution of the “mobile_auth” factor failed. Another factor should be attempted, for example “approve” (recommended) or “passcode”.

The result will be “deny”.

"retry_fallback"

SoundProof authentication failed and reached max consecutive failed attempts. Retry using another factor.

The result will be “deny”.

"timeout_retry"

Authentication failed due to a timeout. The “soundproof”, “approve”, “qr_code” and “mobile_auth” factors time out after 1 minute. The user should retry with the same or other factor.

The result will be “deny”.

"interrupted"

Authentication failed. This authentication session was interrupted because a new session was initiated while this session was still in progress.

The result will be “deny”.

"deny"

Authentication failed. The user may retry.

The 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” 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 result will be “deny”.

"locked_out"

Authentication failed too many times. User is now locked out and needs to be reset (via POST /users/{id}) in order to be able to authenticate again.

The result will be “deny”.

"fraud"

The authentication attempt was reported as fraudulent (the user rejected the approval request).

The result will be “deny”.

"allow"

Authentication was successful.

The result will be “allow”.

status_msg

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 it to the style of your website.

trusted_device_token

This attribute will be present if the authentication was successful (i.e., result was “allow”) and /user/auth or /user/auth/transaction for this particular session had been called with the set_trusted parameter as true.

In this case this, the value be a token that can be used to mark the device from which the authentication attempt took place as trusted. This can later be passed to the /user/preauth endpoint, in order to immediately grant access (without performing secondary authentication), in case the authentication attempt originates from this device.

Example Response

{
    "result": "allow",
    "status": "completed",
    "status_msg": "Login successful",
    "trusted_device_token": "ExANyywJKiI7oNCoYE9FnjVbJZW3QlPY2LFxDBx8CXU="
}

Response  400

Invalid or missing parameters. For example, the specified user_id, username or session_id does not exist.

one_time_code

Generate a new one-time code
POST/user/one_time_code

Generate a new random one-time code. The code is numerical (only digits) and can be used once as secondary authentication for the user.

Your application is responsible of delivering the passcode to the user using a channel, such as SMS, or e-mail.

IMPORTANT: A user can only have one active one-time code at any time. Any previously generated one-time codes, created either through this endpoint or any other means (e.g., calling /user/auth with factor set to “sms”) will be invalidated, as soon as a new one is created.

Example URI

POST https://xxxxxx.futurae.com/srv/auth/v1/user/one_time_code

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

if  username is not specified

ID of the user to be authenticated.

Exactly one of user_id and username must be supplied.

Example: 7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6
username stringrequired

if  user_id is not specified

Username (either specified by your application or generated randomly by Futurae).

Exactly one of user_id and username must be supplied.

Example: user@domain.com
length numberoptional

How long (number of digits) the one-time code should be.

Minimum: 4

Maximum: 20

Default: 6 
valid_secs numberoptional

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

Request was successful.

Response Content

KeyDescription
one_time_code

The newly generated one-time code, formatted with some spacing to make it more readable.

expiration

Time at which this one-time code will expire. Formatted as a UNIX timestamp (in seconds).

Example Response

{
  "one_time_code": "235 094",
  "expiration": 1461694259
}

Response  400

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

© Copyright 2017 Futurae Technologies AG.

Generated by aglio on 15 Nov 2017