NAV Navbar
json

Admin API Reference

The Futurae Admin API provides functionality for managing the users of your application (also referred to as Service) with respect to the use of Futurae authentication, as well as their devices which are used to perform Futurae authentication. It can also be used to retrieve usage information and statistics.

It is generally assumed that before you can make use of the Admin API you have already integrated the Auth API in order to add Futurae authentication and/or transaction signing capabilities to your website or application.

Current Admin API Version: 1.0.1

Version History (change log)

Getting Started

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

The communication with the Futurae server takes place only over TCP port 443, using HTTPS. Please use the provided Service hostname to connect to our servers, and not hardcoded IP addresses as these are subject to change over time.

The Service hostname will typically have the form: xxxxxx.futurae.com, for example api.futurae.com. In this case you would connect to https://api.futurae.com and invoking the endpoints specified in this document.

Request Format

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

Headers

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

The Admin API is based on RESTful API conventions. The URLs are structured to indicate resources under the Admin API prefix and version: /srv/admin/v1/users indicates the set of users resources of the Service, while /srv/admin/v1/users/70d63df1-d20d-4530-ac92-aa6f9f6f329e indicates the specific resource specified by the user_id in the URL. The HTTP verbs used are also following these conventions; GET retrieves the specified resource(s); POST creates a new resource; PUT modifies the (allowed) properties of the specified resource; DELETE archives the specified resource.

Parameters

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

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

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

Input Field Restrictions

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

Request Authentication

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

Authorization header format:

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

Response Format

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

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

This is how an unsuccessful response payload looks like:

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

Unsuccessful responses return an appropriate HTTP response code that conveys the high-level reason of the failure, plus a JSON object of a specified format that might supply some additional details regarding the error. In particular, unsuccessful responses will contain an error boolean field, whose value will be true. Moreover, the response will contain an integer code, and a message field that further describes the failure. A detail field may be present if additional information is available. Example:

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

HTTP Response Codes

Below are listed some common HTTP response codes and their meaning. The codes marked as generic represent generic error codes and could be returned by any endpoint even if they are not explicitly listed in the description of some endpoints.

HTTP Code Meaning Generic
200 The request was successful.
304 The request was processed successfully, but resource was not modified by the request.
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, or the requested resource does not exist.
405 The request HTTP method is not valid for this endpoint (for example, POST when only GET is supported). yes
410 The requested resource has already been archived, and the request cannot modify it any longer.
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

NOTES

The GeoIP features provided by the API include GeoLite2 data created by MaxMind.

Server

Endpoints related to testing communication with the Futurae server.

Ping Server

GET /srv/admin/v1/server/ping

This endpoint can be called to verify that the Futurae server is up. Note that this endpoint does not have to be authenticated with the Authorization header.

Response 200

Example response:

200 OK
{
    "time": 1461694259294
}

Request was successful.

Fields
time
number
UNIX epoch time in milliseconds.

Get API Version

GET /srv/admin/v1/server/api_version

This endpoint can be called in order to retrieve the version of the Futurae Admin API that this server runs. Note that this endpoint does not have to be authenticated with the Authorization header.

Response 200

Example response:

200 OK
{
    "api_version": "1.0.0"
}

Request was successful.

Fields
api_version
string
Futurae Admin API version that this server runs.

Test GET Authorization

Example request query params:

dummy_param=dummy_value&another_param=some_value

GET /srv/admin/v1/server/test

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

Response 200

Example response:

200 OK
{
    "time": 1461694259294
}

Request was successful.

Fields
time
number
UNIX epoch time in milliseconds.

Response 401

Example response:

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

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

Test POST Authorization

Example request body params:

{  
   "dummy_param": "dummy_value"
}

POST /srv/admin/v1/server/test

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

Response 200

Example response:

200 OK
{
    "time": 1461694259294
}

Request was successful.

Fields
time
number
UNIX epoch time in milliseconds.

Response 401

Example response:

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

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

Service

Endpoints related to Service account information and configuration.

Get Service Information

Return Service information.

GET /srv/admin/v1/info

Response 200

Example response:

200 OK
{
    "name": "Cool Company",
    "trial": false,
    "description": "The Futurae Service of Cool Company",
    "expires_at": 1503661649
}

Request was successful.

Fields
name
string
The name of the Service.
trial
boolean
Will be true if this Service account is currently in trial/pilot mode.
description
string
optional
The description of the Service, if any.
expires_at
number
optional
The time at which this Service account expires. Once expired, the account cannot be used to authenticate users and will have only limited functionality, unless renewed. The value is represented as a Unix timestamp and will be visible only if an expiration time exists.

GET /srv/admin/v1/logo

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

Response 200

Example response:

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

Request was successful.

Fields
logo_url
string
The URL from which the logo can be downloaded.

Response 404

Example response:

404 Not Found
{
  "error": true,
  "code": 40400,
  "message": "not found"
}

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

POST /srv/admin/v1/logo

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

Body Parameters

Example request body params:

{
    "logo": "iVBORw0KGgoAAAANSU...(truncated)...bJP/DxeklQAAAABJRU5ErkJggg=="
}
logo
string
required
The PNG image data in Base 64 encoding.

Response 200

Example response:

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

Request was successful.

Fields
logo_url
string
The URL from which the logo can be downloaded.

Response 400

Example response:

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

Missing or invalid parameters.

DELETE /srv/admin/v1/logo

Delete the currently stored logo which is displayed within the Futurae mobile app.

Response 200

Example response:

200 OK
{
    "result": "ok"
}

Request was successful. The stored logo was removed.

Fields
result
string
Always the ok string.

Response 404

Example response:

404 Not Found
{
  "error": true,
  "code": 40400,
  "message": "not found"
}

No logo is currently stored on Futurae. You must first use Upload New Logo to upload a logo, before you can delete it.

Get Users Activity

GET /srv/admin/v1/activity

Get details about the Futurae authentication activity of the users of the Service.

This endpoint retrieves all user authentication activity, formatted in individual activity records, from the time specified in the since parameter and onwards, offset forward by the offset parameter, and with a maximum number of returned records specified by the limit parameter. The records are ordered by the timestamp field of the user activity records, in ascending order.

Query Parameters

Example request query params:

since=1537170000&offset=0&limit=100
since
number
optional
The time since when to retrieve user activity, represented as a Unix timestamp.
Minimum: 0
Default: 0
offset
number
optional
Offset of first record. Combined with limit it can be used to paginate the returned results.
Minimum: 0
Default: 0
limit
number
optional
The maximum number of records to return. Combined with offset it can be used to paginate the returned results.
Minimum: 0 (no records are returned, but the total number of matching records is still returned)
Maximum: 1000
Default: 1000

Response 200

Example response:

200 OK
{
    "activity": [
        {
            "backend_ip": "172.18.0.1",
            "factor": "soundproof",
            "login_device_ip": "172.18.0.1",
            "login_device_location": "GR",
            "result": "allow",
            "timestamp": 1537176804,
            "trusted_device": {
                "app_version": "1.1.2",
                "display_name": "ONEPLUS A3003",
                "id": "710f6ab5-a695-431a-baf8-6d5bfffc40d0",
                "ip": "172.18.0.1",
                "type": "android"
            },
            "user_id": "3d83a68b-c912-48ae-a8ec-224fff6cd155"
        },
        {
            "backend_ip": "172.18.0.1",
            "factor": "qr_code",
            "result": "allow",
            "timestamp": 1537176804,
            "trusted_device": {
                "app_version": "0.0.12",
                "display_name": "ONEPLUS A3003",
                "id": "710f6ab5-a695-431a-baf8-6d5cfb1c40d0",
                "ip": "172.18.0.1",
                "location": "GR",
                "type": "android"
            },
            "user_id": "3d83a68b-c912-48ae-a8ec-224bcdfcd155"
        },
    ],
    "count": 2,
    "limit": 2,
    "offset": 0,
    "total": 24
}

The request was successful, and the requested user authentication activity records are returned.

Fields
count
number
The number of returned records.
total
number
The total number of matching records.
limit
number
The supplied limit param.
offset
number
The supplied offset param.
activity
[object]
The list of User Authentication Activity records, as a JSON array.

Response 400

Example response:

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

Invalid parameters.

Users

Endpoints related to user management. The main resource that these endpoints target is User.

Lookup Users

GET /srv/admin/v1/users

Lookup users based on various filters. Multiple filters can be supplied in a single call and the resulting user records will match all of them at the same time. The results are returned in a paginated fashion and can be ordered in various ways. In case no filters are specified, all the users of your Service will be matched.

Query Parameters

Example request query params:

allowed_factors=approve%2Csoundproof&service_defined_username=true&offset=0&limit=25&sort_by=username&order=asc
username
string
optional
Lookup the user that has the supplied username.
allowed_factors
string
optional
A comma separated list of factors that must be (all) enabled. See Allowed Factors for a description of the possible values.
service_defined_username
boolean
optional
Filter based on whether the username was supplied by your application (true) or was randomly chosen by Futurae (false).
status
string
optional
Filter based on the User Status.
offset
number
optional
Offset of first record. Combined with limit it can be used to paginate the returned results.
Minimum: 0
Default: 0
limit
number
optional
The maximum number of records to return. Combined with offset it can be used to paginate the returned results.
Minimum: 0 (no records are returned, but the total number of matching records is still returned)
Maximum: 100
Default: 25
sort_by
string
optional
Sort the returned results by a specified field.
Available fields: username, created_at, updated_at
Default: created_at
sort_by
string
optional
Choose between ascending (asc) and descending (desc) order for sorting the returned results.
Default: asc

Response 200

Example response:

200 OK
{
    "count": 2,
    "limit": 25,
    "offset": 0,
    "total": 2,
    "users": [
        {
            "allowed_factors": [
                "approve",
                "mobile_totp",
                "passcode",
                "qr_code",
                "sms",
                "soundproof"
            ],
            "created_at": 1496154161,
            "failed_attempts": 0,
            "max_attempts": 40,
            "service_defined_username": true,
            "status": "enabled",
            "updated_at": 1500361673,
            "user_id": "70992f83-4543-11e7-89ab-c241ed9b4fdd",
            "username": "user@domain.com"
        },
        {
            "allowed_factors": [
                "approve",
                "mobile_totp",
                "passcode",
                "qr_code",
                "sms",
                "soundproof"
            ],
            "created_at": 1496167403,
            "display_name": "otheruser@domain.com",
            "failed_attempts": 0,
            "max_attempts": 40,
            "service_defined_username": true,
            "status": "enabled",
            "updated_at": 1498676478,
            "user_id": "458a1d6b-4562-11e7-89ab-c241ed9b4fdd",
            "username": "otheruser@domain.com"
        }
    ]
}

The request was successful.

Fields
count
number
The number of returned records.
total
number
The total number of records that match the specified filters.
limit
number
The supplied limit param.
offset
number
The supplied offset param.
users
[object]
The list of User records, as a JSON array.

Response 400

Example response:

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

Invalid parameters.

Enroll New User

POST /srv/admin/v1/users

This endpoint provides a programmatic way to enroll new users with Futurae authentication. The enrollment of a new user is always accompanied with the enrollment of a device for the user. There are two distinct enrollment cases, depending on whether you wish to enroll a device with the Futurae mobile app installed for use with app-based factors, such as SoundProof, or the phone number of a device that can be used tfor SMS-based authentication.

Enroll New User with Mobile App

POST /srv/admin/v1/users

Create a new user in Futurae and at the same time get an activation code in order to activate a device for this user. In particular, this endpoint invocation will return an activation code as a QR code image (also as a clickable URI) that the Futurae mobile app can scan using the mobile device's built-in camera. Scanning the QR code activates the particular device for the specific user.

Body Parameters

Example request body params:

{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "valid_secs": 3600,
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity"
}
username
string
optional
Unique username for the newly created user. This can serve as an application-specified unique identifier for the user. If not supplied, a random username will be assigned and returned.
See the input restrictions that apply.
display_name
string
optional
An optional display name, which is displayed in the user's Futurae mobile app. As an example, it could be the user's email address.
See the input restrictions that apply.
valid_secs
number
optional
Time, in seconds, for which the activation code will remain valid.
Minimum: 60
Maximum: 7776000 (90 days)
Default: 604800 (7 days)
success_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. The URL will be called as a POST request with Content-Type header being application/json. The body of the request will be a JSON object containing the following fields and corresponding values: user_id, username, activation_code, device_id and result. The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.
The supplied URL must be over https.

Response 200

Example response:

200 OK
{
  "activation_code_uri": "futurae://enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?enroll=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "expiration": 1461694259,
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "username": "someuser@domain.com"
}

Request was successful.

Fields
activation_qrcode_url
string
URL for an image of a scannable QR code with the activation code. This is useful when the user attempts to enable Futurae authentication by accessing his account from a device different than the one on which the Futurae mobile app is installed, for example, when accessing his account from a desktop/laptop computer.
activation_code_uri
string
The activation code in the form of a URI prefixed with the futurae:// scheme. On phones with the Futurae mobile app already installed, it will be a clickable link. This is mostly useful when the user attempts to enable Futurae authentication directly from the device on which the Futurae mobile app is installed (e.g., the URI can be sent via email to be opened directly on the mobile device where the Futurae mobile app is installed and about to be activated).
expiration
number
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds).
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated.

Response 400

Example response:

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

Invalid or missing parameters, or a user with the specified username already exists.

Enroll New User with Phone Number

POST /srv/admin/v1/users

Create a new user in Futurae and at the same time register his phone number in order to activate it for SMS-based authentication. Note that the phone number has to be verified before being able to send SMS one-time codes for authentication. This can be achieved with Auth API's SMS Device Activation.

Body Parameters

Example request body params:

{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "phone_number": "+41123456789"
}
username
string
optional
Unique username for the newly created user. This can serve as an application-specified unique identifier for the user. If not supplied, a random username will be assigned and returned.
See the input restrictions that apply.
display_name
string
optional
An optional display name, which is displayed in the user's Futurae mobile app. As an example, it could be the user's email address.
See the input restrictions that apply.
phone_number
string
required
The phone number of the device in international format.

Response 200

Example response:

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

Request was successful.

Fields
device_id
string
Device ID of the newly created device that has the SMS capability. Use the supplied device ID with Auth API's SMS Device Activation in order to verify the phone number and make it eligible for SMS-based authentication.
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated.

Response 400

Example response:

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

Invalid or missing parameters. In particular, if the supplied phone_number is invalid, the code field within the JSON response will have the value "40001". The response in such a case is shown in the example.

Response 503

Example response:

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

Your subscription does not include the ability to use SMS-based authentication. If you want to be able to use this functionality, please contact sales@futurae.com.

Get User Information

Example request:

GET /srv/admin/v1/users/7adc0abe-4820-4ba8-b8ea-a3eaa2860eb

GET /srv/admin/v1/users/{id}

Get information about the user with Futurae ID id.

Response 200

Example response:

200 OK
{
    "allowed_factors": [
        "approve",
        "mobile_auth",
        "mobile_totp",
        "passcode",
        "qr_code",
        "sms",
        "soundproof"
    ],
    "created_at": 1502893600,
    "display_name": "my display name",
    "failed_attempts": 0,
    "max_attempts": 40,
    "service_defined_username": true,
    "status": "enabled",
    "updated_at": 1502962238,
    "user_id": "eb44cece-828e-11e7-bb14-c241ed9b4fdd",
    "username": "myname@myemail.com"
}

Request was successful. The User record that describes the specified user is returned.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Modify User

PUT /srv/admin/v1/users/{id}

Modify attributes of the user with Futurae ID id. The attributes that can be modified are shown in the table below. for more information on the attributes, see the User resource.

Body Parameters

Example request body params:

{
    "allowed_factors": ["mobile_totp", "soundproof", "soundproof_jingle", "approve", "passcode"],
    "status": "enabled",
    "username": "newusername@domain.com",
    "display_name": "Cooler display name",
    "max_attempts": 15
}
allowed_factors
[string]
optional
A list containing the Futurae authentication technologies which the user is eligible to use. By default, upon user creation the user is eligible for all possible factors, depending on the capabilities of his devices. This default behavior can change by using this endpoint and specifying a more restricted set of allowed factors. See Allowed Factors for a description of the available factors.
status
string
optional
Manipulate the user status.Set to one of the following values:

enabled — Setting to enabled will remove the bypass status, meaning that the user will have to authenticate using Futurae authentication. It will also reset the user to be able to authenticate again, in case he was locked out. Note, however, that if the user has no enrolled devices, his status will immediately become disabled, as he still needs to enroll a new device in order to be able to use Futurae authentication.

bypass — Setting to bypass will allow the user to completely bypass Futurae authentication from now on. It will also reset the user to be able to authenticate again, in case he was locked out.

locked_out — Setting to locked_out will temporarily disable the ability of the user to authenticate with Futurae. His status needs to be reset (i.e., set to enabled or bypass) before he can authenticate again.

disabled — If set to disabled, then any enrolled devices for that user will automatically be unenrolled, and the user will have to enroll a device again in order to authenticate using Futurae authentication. Moreover, similar to setting to enabled, it will reset the bypass or locked_out status (i.e., the user will no more be in bypass mode or locked out).
username
string
optional
Set a new username for this user. The username must be unique. If it is not, the call will result in a 400 error. Note that in order to avoid any issues, make sure that this change is reflected by a change of the username in your application, too.
See the input restrictions that apply.
display_name
string
optional
Set a new display name for this user (displayed in the user's Futurae mobile app). As an example, it could be the user's email address.
See the input restrictions that apply.
max_attempts
number
optional
Set the maximum number of consecutive failed authentication attempts allowed for the user before he gets locked out.
Minimum: 5
Maximum: 40

Response 200

Example response:

200 OK
{
    "status": "enabled",
    "username": "newusername@domain.com",
    "display_name": "Cooler display name"
}

Request was successful. Depending on the supplied request body parameters the response body will contain the values of all the updated user attributes, or it will be empty if no attribute was updated.

Fields
allowed_factors
[string]
optional
The list of the user's allowed factors, if updated.
status
string
optional
The user status, if updated. It will be one of the values described in User Status.
username
string
optional
The username, if updated.
display_name
string
optional
The display name, if updated.

Response 304

Example response:

304 Not Modified

Either no attributes were specified for update, or the specified attributes were the same and thus not modified.

Response 400

Example response:

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

Invalid parameters, or the specified username already exists.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "user already archived"
}

The specified user has already been archived.

Deactivate User

Example request:

DELETE /srv/admin/v1/users/7adc0abe-4820-4ba8-b8ea-a3eaa2860eb

DELETE /srv/admin/v1/users/{id}

Deactivate (archive) the account of the user with ID id.

Response 200

Example response:

200 OK
{
    "result": "ok"
}

Request was successful. The specified user was deactivated.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "user already archived"
}

The specified user has already been archived.

Get User Device Information

GET /srv/admin/v1/users/{id}/devices

Get details about the devices of the user with ID id. The devices can be filtered based on the parameters described below.

Body Parameters

Example request body params:

{

    "status": "enrolled,unenrolled"
}
status
string
optional
A comma-separated list of status strings of devices to return. All devices that match any of the provided status strings will be returned. If omitted, all the devices will be returned. The available values are enrolled, unenrolled and archived.

Response 200

Example response:

200 OK
{
    "count": 1,
    "devices": [
        {
            "capabilities": [
                "mobile_totp",
                "approve",
                "qr_code",
                "soundproof"
            ],
            "created_at": 1503581926,
            "device_id": "da1e3c29-8751-11e7-8189-c241ed9b4fdd",
            "display_name": "my android phone",
            "enrolled": true,
            "enrolled_at": 1503581926,
            "type": "android",
            "updated_at": 1503581926,
            "user_id": "8dd64244-88d1-11e7-b00b-0242ac120003",
            "version": "1.0.0",
            "version_supported": true
        }
    ]
}

Request was successful.

Fields
count
number
The number of matching devices of the specified user, that are returned by this endpoint.
devices
[object]
The list of matching Device records that belong to the user.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Enroll New User Device

POST /srv/admin/v1/users/{id}/devices

Initiate the enrollment of a new device for the user with ID id. There are two distinct enrollment cases, depending on whether you are enrolling a device with the Futurae app installed for use with app-based factors, such as SoundProof, or the phone number of a device that can be used to for SMS-based authentication.

Enroll New Mobile App

POST /srv/admin/v1/users/{id}/devices

Get an activation code in order to activate a device for this user. In particular, this endpoint invocation will return an activation code as a QR code image (also as a clickable URI) that the Futurae mobile app can scan using the mobile device's built-in camera. Scanning the QR code activates the particular device for the specific user.

Body Parameters

Example request body params:

{
    "valid_secs": 3600,
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity"
}
valid_secs
number
optional
Time, in seconds, for which the activation code will remain valid.
Minimum: 60
Maximum: 7776000 (90 days)
Default: 604800 (7 days)
success_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. The URL will be called as a POST request with Content-Type header being application/json. The body of the request will be a JSON object containing the following fields and corresponding values: user_id, username, activation_code, device_id and result. The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.
The supplied URL must be over https.

Response 200

Example response:

200 OK
{
  "activation_code_uri": "futurae://enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?enroll=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "expiration": 1461694259,
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "username": "someuser@domain.com"
}

Request was successful.

Fields
activation_qrcode_url
string
URL for an image of a scannable QR code with the activation code. This is useful when the user attempts to enable Futurae authentication by accessing his account from a device different than the one on which the Futurae mobile app is installed, for example, when accessing his account from a desktop/laptop computer.
activation_code_uri
string
The activation code in the form of a URI prefixed with the futurae:// scheme. On phones with the Futurae mobile app already installed, it will be a clickable link. This is mostly useful when the user attempts to enable Futurae authentication directly from the device on which the Futurae mobile app is installed (e.g., the URI can be sent via email to be opened directly on the mobile device where the Futurae mobile app is installed and about to be activated).
expiration
number
Time at which this activation code will expire. Formatted as a Unix timestamp (in seconds).
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated.

Response 400

Example response:

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

Invalid or missing parameters.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "user already archived"
}

The specified user has already been archived.

Enroll New Phone Number

POST /srv/admin/v1/users/{id}/devices

Register a new phone number in order to activate it for SMS-based authentication. Note that the phone number has to be verified before being able to send SMS one-time codes for authentication. This can be achieved with Auth API's SMS Device Activation.

Body Parameters

Example request body params:

{
    "phone_number": "+41123456789"
}
phone_number
string
required
The phone number of the device in international format.

Response 200

Example response:

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

Request was successful.

Fields
device_id
string
Device ID of the newly created device that has the SMS capability. Use the supplied device ID with Auth API's SMS Device Activation in order to verify the phone number and make it eligible for SMS-based authentication.
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
Unique identifier for the user in Futurae. Either specified as a parameter or auto-generated.

Response 400

Example response:

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

Invalid or missing parameters. In particular, if the supplied phone_number is invalid, the code field within the JSON response will have the value "40001". The response in such a case is shown in the example.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "user already archived"
}

The specified user has already been archived.

Response 503

Example response:

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

Your subscription does not include the ability to use SMS-based authentication. If you want to be able to use this functionality, please contact sales@futurae.com.

Get User Enrollment Information

Example request:

GET /srv/admin/v1/users/7adc0abe-4820-4ba8-b8ea-a3eaa2860eb/enrollments

GET /srv/admin/v1/users/{id}/enrollments

Get details about the enrollments of the user with ID id.

Response 200

Example response:

200 OK
{
    "count": 2,
    "enrollments": [
        {
            "activation_code": "CQJUlLMhG8Ox807lJMec1nHj2nfoPVBVBcoJSbH0qjs=",
            "activation_qrcode_url": "https://futurae.com/qr?enroll=CQJUlLMhG8Ox807lJMec1nHj2nfoPVBVBcoJSbH0qjs=",
            "created_at": 1503056849,
            "expires_at": 1503661649,
            "status": "pending",
            "updated_at": 1503056849,
            "user_id": "b91aa475-83f3-11e7-9a9d-0242ac120003"
        },
        {
            "activation_code": "T_d0fmqJe77rrlPfyiExiWmeCq1J6vYQYqRu_sWNoKA=",
            "activation_qrcode_url": "https://futurae.com/qr?enroll=T_d0fmqJe77rrlPfyiExiWmeCq1J6vYQYqRu_sWNoKA=",
            "created_at": 1503046846,
            "enrolled_device_id": "b927b436-83f3-11e7-9a9d-0242ac120003",
            "expires_at": 1503651646,
            "status": "success",
            "updated_at": 1503046846,
            "user_id": "b91aa475-83f3-11e7-9a9d-0242ac120003"
        }
    ]
}

Request was successful.

Fields
count
number
The number of enrollments of the specified user, that are returned by this endpoint.
enrollments
[object]
The list of Enrollment records that belong to the user.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Get Backup Codes

Example request:

GET /srv/admin/v1/users/7adc0abe-4820-4ba8-b8ea-a3eaa2860eb/backup_codes

GET /srv/admin/v1/users/{id}/backup_codes

Get the list of the backup authentication codes for the user with ID id.

Response 200

Example response:

200 OK
{
    "backup_codes": [
        {
            "code": "044 675 761 383",
            "remaining_uses": 1
        },
        {
            "code": "446 723 759 935",
            "remaining_uses": 1
        },
        {
            "code": "041 151 008 145",
            "remaining_uses": 1
        }
    ]
}

Request was successful.

Fields
backup_codes
[object]
The list of backup codes of the specified user. Each backup code object, contains the following fields:

code — A string value representing the backup code, formatted with spacing for readability.

remaining_uses — If the backup codes have been generated with a finite number of uses, this number counter shows how many are remaining before the code cannot be reused; otherwise this will not be present.

infinite_uses — If the backup codes have been generated with an infinite number of uses, this boolean value will be true; otherwise this will not be present.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Generate Backup Codes

POST /srv/admin/v1/users/{id}/backup_codes

This endpoint clears the entire existing (if any) list of backup authentication codes and generates a fresh list, for the user with ID id. The codes are numerical (only digits) and generated randomly. Your application should show the codes to the user. The user should store the backup codes safely and use them to authenticate in case he has lost access to his devices.

Body Parameters

Example request body params:

{
    "length": 8,
    "reuse_count": 1
}
count
number
optional
How many codes to generate.
Minimum: 1
Maximum: 10
Default: 10
length
number
optional
How long (number of digits) each code should be.
Minimum: 8
Maximum: 20
Default: 10
reuse_count
number
optional
The number of times each of the generated code can be used for authentication. Ideally it should be that they are only used once.
If set to 0, then the codes can be reused infinitely many times (not recommended).
Default: 1

Response 200

Example response:

200 OK
{
    "backup_codes": [
        {
            "code": "733 230 306 367",
            "infinite_uses": true
        },
        {
            "code": "725 763 845 836",
            "infinite_uses": true
        },
        {
            "code": "098 425 747 866",
            "infinite_uses": true
        }
    ]
}

Request was successful.

Fields
backup_codes
[object]
The list of backup codes of the specified user. Each backup code object, contains the following fields:

code — A string value representing the backup code, formatted with spacing for readability.

remaining_uses — If the backup codes have been generated with a finite number of uses, this number counter shows how many are remaining before the code cannot be reused; otherwise this will not be present.

infinite_uses — If the backup codes have been generated with an infinite number of uses, this boolean value will be true; otherwise this will not be present.

Response 400

Example response:

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

Invalid parameters.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "user already archived"
}

The specified user has already been archived.

Generate One-Time Code

POST /srv/admin/v1/users/{id}/one_time_code

Generate a new random one-time code. The code is numerical (only digits) and can be used once by the use to successfully complete Futurae authentication.

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

Body Parameters

Example request body params:

{
    "valid_secs": 60
}
length
number
optional
How long (number of digits) the one-time code should be.
Minimum: 4
Maximum: 20
Default: 6
valid_secs
number
optional
Time, in seconds, for which the one-time code will remain valid.
Minimum: 60 (1 minute)
Maximum: 1800 (30 minute)
Default: 180 (3 minutes)

Response 200

Example response:

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

Request was successful.

Fields
one_time_code
string
The newly generated one-time code, formatted with some spacing to make it more readable.
expiration
number
Time at which this one-time code will expire. Formatted as a Unix timestamp (in seconds).

Response 400

Example response:

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

Invalid parameters.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "user already archived"
}

The specified user has already been archived.

Get User Activity

GET /srv/admin/v1/users/{id}/activity

Get details about the Futurae authentication activity of the user with ID id.

This endpoint retrieves the user's authentication activity, formatted in individual activity records, from the time specified in the since parameter and onwards, offset forward by the offset parameter, and with a maximum number of returned records specified by the limit parameter. The records are ordered by the timestamp field of the user activity records, in ascending order.

Query Parameters

Example request query params:

since=1537170000&offset=0&limit=100
device_id
string
optional
The ID of a specific device of the user, to query activity for.
since
number
optional
The time since when to retrieve user activity, represented as a Unix timestamp.
Minimum: 0
Default: 0
offset
number
optional
Offset of first record. Combined with limit it can be used to paginate the returned results.
Minimum: 0
Default: 0
limit
number
optional
The maximum number of records to return. Combined with offset it can be used to paginate the returned results.
Minimum: 0 (no records are returned, but the total number of matching records is still returned)
Maximum: 1000
Default: 1000

Response 200

Example response:

200 OK
{
    "activity": [
        {
            "backend_ip": "172.18.0.1",
            "factor": "soundproof",
            "login_device_ip": "172.18.0.1",
            "result": "allow",
            "timestamp": 1537176804,
            "trusted_device": {
                "app_version": "1.1.2",
                "display_name": "ONEPLUS A3003",
                "id": "710f6ab5-a695-431a-baf8-6d5bfffc40d0",
                "ip": "172.18.0.1",
                "type": "android"
            },
            "user_id": "3d83a68b-c912-48ae-a8ec-224fff6cd155"
        },
        {
            "backend_ip": "172.18.0.1",
            "factor": "approve",
            "result": "allow",
            "timestamp": 1537176804,
            "trusted_device": {
                "app_version": "1.1.2",
                "display_name": "ONEPLUS A3003",
                "id": "710f6ab5-a695-431a-baf8-6d5bfffc40d0",
                "ip": "172.18.0.1",
                "type": "android"
            },
            "user_id": "3d83a68b-c912-48ae-a8ec-224fff6cd155"
        },
        {
            "backend_ip": "172.18.0.1",
            "factor": "mobile_totp",
            "result": "allow",
            "timestamp": 1537176804,
            "trusted_device": {
                "app_version": "1.1.2",
                "display_name": "ONEPLUS A3003",
                "id": "710f6ab5-a695-431a-baf8-6d5bfffc40d0",
                "ip": "172.18.0.1",
                "type": "android"
            },
            "user_id": "3d83a68b-c912-48ae-a8ec-224fff6cd155"
        },
    ],
    "count": 3,
    "limit": 3,
    "offset": 0,
    "total": 24
}

The request was successful, and the requested user authentication activity records are returned.

Fields
count
number
The number of returned records.
total
number
The total number of matching records.
limit
number
The supplied limit param.
offset
number
The supplied offset param.
activity
[object]
The list of User Authentication Activity records, as a JSON array.

Response 400

Example response:

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

Invalid parameters.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified user id does not exist.

Devices

Endpoints related to device management. The main resource that these endpoints target is the Device record.

Enroll New Device

POST /srv/admin/v1/devices

Initiate the enrollment of a new device. This is identical to Enroll New User Device. However, instead of specifying the user ID as a resource in the URL, it is specified in the body of the request as shown below.

Body Parameters

Example request body params:

{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "valid_secs": 3600,
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity"
}
user_id
string
required
The ID of the user to enroll a new device for.

Get Device Details

Example request:

GET /srv/admin/v1/devices/af799248-7389-11e7-ac03-0242ac120003

GET /srv/admin/v1/devices/{id}

Get information about the device with ID id.

Response 200

Example response:

200 OK
{
    "capabilities": [
        "mobile_totp",
        "approve",
        "qr_code",
        "soundproof"
    ],
    "created_at": 1503581926,
    "device_id": "af799248-7389-11e7-ac03-0242ac120003",
    "display_name": "my android phone",
    "enrolled": true,
    "enrolled_at": 1503581926,
    "type": "android",
    "updated_at": 1503581926,
    "user_id": "8dd64244-88d1-11e7-b00b-0242ac120003",
    "version": "1.0.0",
    "version_supported": true
}

The request was successful. The corresponding Device record is returned

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified device id does not exist.

Modify Device

PUT /srv/admin/v1/devices/{id}

Modify the device details for the device with ID id. Currently only the modification of the display_name field is possible.

Body Parameters

Example request body params:

{
    "display_name": "My iphone"
}
display_name
string
optional
Sets a custom display name for that particular device. Useful for when a user has multiple devices enrolled with his account. It can serve as a (usually) user-chosen mnemonic name to help the user choose which device he wishes to use for Futurae authentication. By default, the display name is the device model (or the phone number for SMS devices).

Response 200

Example response:

200 OK
{
    "display_name": "My iphone"
}

Request was successful. Depending on the supplied request body parameters the response body will contain the values of the attributes, or it will be empty if no attribute was updated.

Fields
display_name
string
optional
The device display name, if updated.

Response 304

Example response:

304 Not Modified

Either no attributes were specified for update, or the specified attributes were the same and thus not modified.

Response 400

Example response:

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

Invalid parameters.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified device id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "device already archived"
}

The specified device has already been archived.

Unenroll Device

Example request:

DELETE /srv/admin/v1/devices/af799248-7389-11e7-ac03-0242ac120003

DELETE /srv/admin/v1/devices/{id}

Unenroll (archive) a device of a user. If the specified device is the only enrolled device for the user, then Futurae authentication will automatically be disabled for this user (his User Status will change to disabled). The user will have to enroll a device again in order to be able to authenticate using Futurae authentication.

Response 200

Example response:

200 OK
{
    "result": "success"
}

Request was successful.

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

success — The specified device was successfully unenrolled.

success_2fa_disabled — The specified device was successfully unenrolled. Moreover, this was the only enrolled device for the user, therefore Futurae authentication was automatically disabled for that user (his User Status is now changed to disabled).

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified device id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "device already archived"
}

The specified device has already been archived.

Enrollments

Endpoints related to enrollment management. The main resource that these endpoints target is the Enrollment record.

Get Enrollments

GET /srv/admin/v1/enrollments

Lookup enrollments based on various filters. Multiple filters can be supplied in a single call and the resulting enrollment records will match all of them at the same time. The results are returned in a paginated fashion and can be ordered in various ways. In case no filters are specified, all the enrollments of the Service will be matched.

Query Parameters

Example request query params:


user_id=7aa23410-8899-11e7-9f92-0242ac120003&offset=0&limit=25&sort_by=expires_at&order=asc
user_id
string
optional
Filter on the user ID of an enrollment.
enrolled_device_id
string
optional
Filter on the device ID that got enrolled with this enrollment.
created_since
number
optional
Search for enrollments created since the specified timestamp (represented as a Unix timestamp).
Minimum: 0
created_until
number
optional
Search for enrollments created until the specified timestamp (represented as a Unix timestamp).
Minimum: 0
expires_since
number
optional
Search for enrollments that expire since the specified timestamp (represented as a Unix timestamp).
Minimum: 0
expires_until
number
optional
Search for enrollments that expire until the specified timestamp (represented as a Unix timestamp).
Minimum: 0
status
string
optional
Filter based on the Enrollment Status.
offset
number
optional
Offset of first record. Combined with limit it can be used to paginate the returned results.
Minimum: 0
Default: 0
limit
number
optional
The maximum number of records to return. Combined with offset it can be used to paginate the returned results.
Minimum: 0 (no records are returned, but the total number of matching records is still returned)
Maximum: 100
Default: 25
sort_by
string
optional
Sort the returned results by a specified field.
Available fields: created_at, expires_at, user_id
Default: created_at
sort_by
string
optional
Choose between ascending (asc) and descending (desc) order for sorting the returned results.
Default: asc

Response 200

Example response:

200 OK
{
    "count": 2,
    "enrollments": [
        {
            "activation_code": "2z2Qm1gPCGL6VwN-3SpJwG18C5ARtm0wMRaN3U_Ck0E=",
            "activation_qrcode_url": "https://futurae.com/qr?enroll=2z2Qm1gPCGL6VwN-3SpJwG18C5ARtm0wMRaN3U_Ck0E=",
            "created_at": 1503557842,
            "expires_at": 1503560272,
            "status": "expired",
            "updated_at": 1503557842,
            "user_id": "7aa23410-8899-11e7-9f92-0242ac120003"
        },
        {
            "activation_code": "G4nSSly7nLmrZ1pVpD1C2FzO0wmJzzjy9z3pFSqYdyU=",
            "activation_qrcode_url": "https://futurae.com/qr?enroll=G4nSSly7nLmrZ1pVpD1C2FzO0wmJzzjy9z3pFSqYdyU=",
            "created_at": 1503557842,
            "enrolled_device_id": "7aae4614-8899-11e7-9f92-0242ac120003",
            "expires_at": 1504162642,
            "status": "success",
            "updated_at": 1503557842,
            "user_id": "7aa1ca24-8899-11e7-9f92-0242ac120003"
        },
    ],
    "limit": 25,
    "offset": 0,
    "total": 2
}

The request was successful.

Fields
count
number
The number of returned records.
total
number
The total number of records that match the specified filters.
limit
number
The supplied limit param.
offset
number
The supplied offset param.
enrollments
[object]
The list of Enrollment records, as a JSON array.

Response 400

Example response:

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

Invalid parameters.

Get Enrollment Details

Example request:

GET /srv/admin/v1/enrollments/G4nSSly7nLmrZ1pVpD1C2FzO0wmJzzjy9z3pFSqYdyU=

GET /srv/admin/v1/enrollments/{id}

Retrieve the details of the enrollment with activation code id.

Response 200

Example response:

200 OK
{
    "activation_code": "G4nSSly7nLmrZ1pVpD1C2FzO0wmJzzjy9z3pFSqYdyU=",
    "activation_qrcode_url": "https://futurae.com/qr?enroll=G4nSSly7nLmrZ1pVpD1C2FzO0wmJzzjy9z3pFSqYdyU=",
    "created_at": 1503557842,
    "enrolled_device_id": "7aae4614-8899-11e7-9f92-0242ac120003",
    "expires_at": 1504162642,
    "status": "success",
    "updated_at": 1503557842,
    "user_id": "7aa1ca24-8899-11e7-9f92-0242ac120003"
}

Request was successful. The Enrollment record that describes the specified enrollment is returned.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified enrollment id does not exist.

Modify Enrollment

PUT /srv/admin/v1/enrollments/{id}

Modify attributes of the enrollment with activation code id. The attributes that can be modified are shown in the below.

Body Parameters

Example request body params:

{
    "expires_at": 1503056850
}
expires_at
number
optional
The expiration time of this enrollment, represented as a Unix timestamp. It is possible to update the expiration time of an enrollment, even if it has already expired. When an enrollment has been archived or completed (i.e., when Enrollment Status is archived or success), it is not possible to update the expiration time.
The new timestamp should be at most 90 days in the future.
success_callback_url
string
optional
The URL to be used for the success callback. It is not possible to update this attribute for completed or archived enrollments (i.e., when Enrollment Status is archived or success).

Response 200

Example response:

200 OK
{
    "expires_at": 1503056850
}

Request was successful, and the requested enrollment has been modified successfully. The updated attributes are returned.

Fields
expires_at
number
optional
The expiration time, if updated.
success_callback_url
string
optional
The success callback URL, if updated.

Response 304

Example response:

304 Not Modified

Either no attributes were specified for update, or the specified attributes were the same and thus not modified.

Response 400

Example response:

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

Invalid parameters.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified enrollment id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "enrollment already archived"
}

The specified enrollment has already been archived or completed.

Invalidate Enrollment

Example request:

DELETE /srv/admin/v1/enrollments/G4nSSly7nLmrZ1pVpD1C2FzO0wmJzzjy9z3pFSqYdyU=

DELETE /srv/admin/v1/enrollments/{id}

Invalidate and archive the enrollment with activation code id. After this the enrollment will no longer be available to use, nor it will be possible to modify it with Modify Enrollment.

Response 200

Example response:

200 OK
{
    "result": "ok"
}

Request was successful. The enrollment has been invalidated.

Response 404

Example response:

404 Not Found
{
    "error": true,
    "code": 40400,
    "message": "not found"
}

The specified enrollment id does not exist.

Response 410

Example response:

410 Gone
{
    "error": true,
    "code": 41000,
    "message": "gone",
    "detail": "enrollment already archived"
}

The specified enrollment has already been archived.

Statistics

Endpoints for retrieving various statistics related to the use of Futurae authentication.

Get Users Statistics

GET /srv/admin/v1/stats/users

Retrieve users statistics. These include total users statistics as well as aggregated stats over the requested time period.

Query Parameters

Example request query params:

since=1504224000&until=1506729600&group_by=month
since
number
optional
Time since when to fetch stats (Unix timestamp).
Default: Beginning of current month.
Minimum: 2 years in the past.
until
number
optional
Time until when to fetch stats (Unix timestamp).
Default: End of current month.
Maximum: End of current month.
group_by
string
optional
Group the statistics by year, month, or day.
Choices: year, month, day
Default: month

Response 200

Example response:

200 OK
{
    "2fa_bypass": 0,
    "2fa_disabled": 19,
    "2fa_enabled": 111,
    "aggregation": {
        "group_by": "month",
        "groups": [
            {
                "year": 2017,
                "month": 7,
                "total": 115,
                "2fa_bypass": 0,
                "2fa_enabled": 103,
                "2fa_disabled": 12,
                "locked_out": 0
            },
            {
                "year": 2017,
                "month": 8,
                "total": 128,
                "2fa_bypass": 0,
                "2fa_enabled": 108,
                "2fa_disabled": 20,
                "locked_out": 0
            },
            {
                "year": 2017,
                "month": 9,
                "total": 130,
                "2fa_bypass": 0,
                "2fa_enabled": 111,
                "2fa_disabled": 19,
                "locked_out": 0
            }
        ],
        "since": 1498867200,
        "until": 1506815999
    },
    "locked_out": 0,
    "total": 130
}

The request was successful. The statistics overview is returned in a single JSON response object.

Fields
total
number
The total number of users of the Service.
2fa_bypass
number
The number of users configured to bypass Futurae authentication.
2fa_enabled
number
The number of users for which Futurae authentication is enabled.
2fa_disabled
number
The number of users for which Futurae authentication is disabled.
locked_out
number
The number of users that are locked out (either set programmatically, or due to a large number of failed authentication attempts).
aggregation
object
An Aggregation object that contains the aggregated results according to the query parameters. Each aggregation group, besides the fields defining the time interval of the group, will contain the above mentioned fields of this table.

Response 400

Example response:

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

Invalid parameters.

Get Active Users Statistics

GET /srv/admin/v1/stats/users/active

Retrieve statistics about active users. The statistics are limited and aggregated by the requested period.

Query Parameters

Example request query params:

since=1504224000&until=1506729600&group_by=month
since
number
optional
Time since when to fetch stats (Unix timestamp).
Default: Beginning of current month.
Minimum: 2 years in the past.
until
number
optional
Time until when to fetch stats (Unix timestamp).
Default: End of current month.
Maximum: End of current month.
group_by
string
optional
Group the statistics by year, month, or day.
Choices: year, month, day
Default: month

Response 200

Example response:

200 OK
{
    "aggregation": {
        "group_by": "month",
        "groups": [
            {
                "year": 2017,
                "month": 9,
                "active": 9
            }
        ],
        "since": 1504224000,
        "until": 1506815999
    }
}

The request was successful. The statistics overview is returned in a single JSON response object.

Fields
aggregation
object
An Aggregation object that contains the aggregated results according to the query parameters. Each aggregation group, besides the fields defining the time interval of the group, will contain the following additional fields:

active — The number of active users during the time period described by the group.

Response 400

Example response:

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

Invalid parameters.

Get Users Activity Statistics

GET /srv/admin/v1/stats/activity

Retrieve statistics about the Futurae authentication activity of the users of your Service. The statistics are limited and aggregated by the requested period.

Query Parameters

Example request query params:

since=1504224000&until=1506729600&group_by=month
since
number
optional
Time since when to fetch stats (Unix timestamp).
Default: Beginning of current month.
Minimum: 2 years in the past.
until
number
optional
Time until when to fetch stats (Unix timestamp).
Default: End of current month.
Maximum: End of current month.
group_by
string
optional
Group the statistics by year, month, or day.
Choices: year, month, day
Default: month

Response 200

Example response:

200 OK
{
    "aggregation": {
        "group_by": "month",
        "groups": [
            {
                "year": 2017,
                "month": 9,
                "2fa_allowed": 103,
                "2fa_denied": 9,
                "bypass": 1,
                "disabled": 45,
                "locked_out": 0,
                "trusted_token": 0,
                "factors": {
                    "approve": {
                        "allowed": 18,
                        "denied": 1
                    },
                    "mobile_totp": {
                        "allowed": 3,
                        "denied": 0
                    },
                    "passcode": {
                        "allowed": 4,
                        "denied": 2
                    },
                    "qr_code": {
                        "allowed": 11,
                        "denied": 0
                    },
                    "soundproof": {
                        "allowed": 67,
                        "denied": 6
                    }
                }
            }
        ],
        "since": 1504224000,
        "until": 1506815999
    }
}

The request was successful. The statistics overview is returned in a single JSON response object.

Fields
aggregation
object
An Aggregation object that contains the aggregated results according to the query parameters. Each aggregation group, besides the fields defining the time interval of the group, will contain the following additional fields:

2fa_allowed — The total number of successful authentication attempts.

2fa_denied — The total number of unsuccessful authentication attempts.

bypass — The number of attempts that were allowed due to authentication bypass.

disabled — The number of attempts that were denied due to a user being disabled.

locked_out — The number of attempts that were denied due to a user being locked out.

trusted_token — The number of attempts that were allowed due to a trusted device token.

factors — A JSON object containing authentication statistics broken down for each authentication factor used. Each factor is a field of this object and its value is an object containing allowed and denied fields with the number of successful and unsuccessful attempt respectively.

Response 400

Example response:

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

Invalid parameters.

Get Devices Statistics

GET /srv/admin/v1/stats/devices

Retrieve user devices statistics, limited and aggregated by the requested period.

Query Parameters

Example request query params:

since=1504224000&until=1506729600&group_by=month
since
number
optional
Time since when to fetch stats (Unix timestamp).
Default: Beginning of current month.
Minimum: 2 years in the past.
until
number
optional
Time until when to fetch stats (Unix timestamp).
Default: End of current month.
Maximum: End of current month.
group_by
string
optional
Group the statistics by year, month, or day.
Choices: year, month, day
Default: month

Response 200

Example response:

200 OK
{
    "aggregation": {
        "group_by": "month",
        "groups": [
            {
                "year": 2017,
                "month": 9,
                "total": 110,
                "ios": {
                    "1.0.2": 2
                },
                "android": {
                    "0.0.12": 1,
                    "0.0.14": 1,
                    "n/a": 106
                }
            }
        ],
        "since": 1504224000,
        "until": 1506815999
    },
    "android": {
        "0.0.12": 1,
        "0.0.14": 1,
        "n/a": 106
    },
    "ios": {
        "1.0.2": 2
    },
    "total": 110
}

The request was successful. The statistics overview is returned in a single JSON response object.

Fields
total
number
The total number of enrolled devices.
ios
object
Statistics for iOS devices. In particular the number of devices for each Futurae mobile app version.
android
object
Statistics for Android devices. In particular the number of devices for each Futurae mobile app version.
aggregation
object
An Aggregation object that contains the aggregated results according to the query parameters. Each aggregation group, besides the fields defining the time interval of the group, will contain the above mentioned fields of this table.

Response 400

Example response:

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

Invalid parameters.

Get Enrollments Statistics

GET /srv/admin/v1/stats/enrollments

Retrieve enrollments statistics. The statistics return correspond to the total numbers of enrollments in the system for the specified timeframe.

Query Parameters

Example request query params:

since=1504224000&until=1506729600
since
number
optional
Time since when to fetch stats (Unix timestamp).
Default: Beginning of current month.
Minimum: 2 years in the past.
until
number
optional
Time until when to fetch stats (Unix timestamp).
Default: End of current month.
Maximum: End of current month.

Response 200

Example response:

200 OK
{
    "expired": 20,
    "pending": 1,
    "success": 268,
    "total": 289,
    "since": 1504224000,
    "until": 1506815999
}

The request was successful. The statistics overview is returned in a single JSON response object.

Fields
total
number
The total number of enrollments of the service.
pending
number
The number of pending enrollments.
success
number
The number of enrollments that have been successfully completed.
expired
number
The number of enrollments that have already expired without having been completed.
since
number
The since parameter supplied in the query.
until
number
The until parameter supplied in the query.

Response 400

Example response:

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

Invalid parameters.

Get GeoIP Statistics

GET /srv/admin/v1/stats/geo

Retrieve GeoIP statistics for the mobile and browser clients of the service.

Query Parameters

Example request query params:

since=1504224000&until=1506729600
since
number
optional
Time since when to fetch stats (Unix timestamp).
Default: Beginning of current month.
Minimum: 2 years in the past.
until
number
optional
Time until when to fetch stats (Unix timestamp).
Default: End of current month.
Maximum: End of current month.

Response 200

Example response:

200 OK
{
    "login_dev_iso_country": {
        "CH": {
            "country_name": "Switzerland",
            "success": 22,
            "total": 23,
            "users": 10
        },
        "total": 23
    },
    "since": 1504224000,
    "trusted_dev_iso_country": {
        "CH": {
            "country_name": "Switzerland",
            "success": 87,
            "total": 90,
            "users": 47
        },
        "total": 113
    },
    "until": 1506815999
}

The request was successful. The statistics overview is returned in a single JSON response object.

Fields
login_dev_iso_country
object
An object containing the total count, as well as a break down per ISO Country Code, of IPs with recorded activity for the requested timeframe, that correspond to the IP of the login device (e.g., a web browser). Each country code is associated with an object containing the following fields:

country_name — The full name of the country.

total — The total number of IPs with recorded activity for the country.

success — The number of IPs with successful recorded activity for the country.

users — The number of distinct users with successful recorded activity for the country.
trusted_dev_iso_country
object
An object containing the total count, as well as a break down per ISO Country Code, of IPs with recorded activity for the requested timeframe, that correspond to the IP of the user trusted device used (typically the Futurae mobile app). Each country code is associated with an object containing the following fields:

country_name — The full name of the country.

total — The total number of IPs with recorded activity for the country.

success — The number of IPs with successful recorded activity for the country.

users — The number of distinct users with successful recorded activity for the country.
since
number
The since parameter supplied in the query.
until
number
The until parameter supplied in the query.

Response 400

Example response:

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

Invalid parameters.

Resources

User

This resource represents a user registered in Futurae. A Futurae user should be associated with a user in your application. You register a user in Futurae in order to enable him to authenticate using Futurae authentication. The User resource is defined in the following table:

Example User object:

{
    "allowed_factors": [
        "approve",
        "mobile_totp",
        "passcode",
        "qr_code",
        "sms",
        "soundproof"
    ],
    "created_at": 1496154161,
    "failed_attempts": 0,
    "max_attempts": 40,
    "service_defined_username": true,
    "status": "enabled",
    "updated_at": 1500361673,
    "user_id": "70992f83-4543-11e7-89ab-c241ed9b4fdd",
    "username": "user@domain.com"
}
Fields
user_id
string
The Futurae ID of this user.
username
string
The username of the user. This serves as an alternative identifier which can be specified by your application, or generated randomly by Futurae.
display_name
string
An optional display name for the user, which is displayed in the user's Futurae mobile app.
allowed_factors
[string]
A list of the authentication factors that are permitted to be used for this user. One or more of the factors described in Allowed Factors will be contained in the list.
failed_attempts
number
The number of consecutive failed authentication attempts that the user has made.
max_attempts
number
The maximum number of consecutive failed authentication attempts allowed for the user before he gets locked out.
service_defined_username
boolean
Indicates whether the user has been assigned a username from your application (true) or an automatically generated one (false).
status
string
A description of the status of the user. The possible values are described in User Status.
created_at
number
The time when this user was created, represented as a Unix timestamp.
updated_at
number
The time when this user was last updated, represented as a Unix timestamp.
archived_at
number
optional
The time when this user was archived, if applicable, represented as a Unix timestamp.

Allowed Factors

Allowed factors are string values that represent which Futurae authentication technologies a user is eligible to use. The allowed factors of a user can be configured via Modify User.

The table below lists all different factors:

Factors
approve Authentication based on approvals received through push notifications (aka One-Touch).
mobile_auth Single device authentication, i.e., when logging in from a device on which the Futurae mobile app is installed and enrolled for this particular user. Refer to the respective Auth API guide section for more information.
mobile_totp Generate time-based one-time codes from within the Futurae mobile app on the user device.
passcode Authentication based on any type of one-time code (including mobile_totp above). The user-submitted code can be verified with Auth API's Authenticate with Passcode.
qr_code Authentication based on QR code scanning.
sms Receive SMS one-time codes (SMS-based authentication).
soundproof SoundProof authentication (aka Zero-Touch), based on comparison of background ambient sounds and inaudible, near-ultrasound pattern emission.
soundproof_jingle SoundProof authentication, based on jingle emission (aka Zero-Touch Jingle).

User Authentication Activity

This resource represents a user Futurae authentication activity record and is defined in the following table:

Example User Activity object:

{
    "backend_ip": "172.18.0.1",
    "factor": "soundproof",
    "login_device_ip": "172.18.0.1",
    "login_device_location": "GR",
    "result": "allow",
    "timestamp": 1537176804,
    "trusted_device": {
        "app_version": "1.1.2",
        "display_name": "ONEPLUS A3003",
        "id": "710f6ab5-a695-431a-baf8-6d5bfffc40d0",
        "ip": "172.18.0.1",
        "location": "GR",
        "type": "android"
    },
    "user_id": "3d83a68b-c912-48ae-a8ec-224fff6cd155"
}
Fields
user_id
string
The ID of the user.
timestamp
number
The time at which the user activity record occurred, represented as a Unix timestamp.
factor
string
The authentication factor used for this record. This is not present when the activity record took place when the User Status was bypass, disabled or locked_out, or if authentication succeeded with a trusted device token.
result
string
The result of the authentication for this user activity. Either allow or deny.
type
string
optional
The type of authentication that this activity represents, if applicable (e.g., Login, Transaction).
reason
string
optional
Further information on the authentication result, if available. This might contain for example the exact type of passcode factor used (mobile_totp, backup_code, etc.), and also information on why the attempt might have failed (e.g. backup_code unusable when a backup code is not usable anymore, or one_time_code expired).
backend_ip
string
optional
The IP address of the backend server of your application that issued the authentication request to the Futurae server, if available.
login_device_ip
string
optional
The IP address of the device on which the authentication activity is taking place, if available.
login_device_location
string
optional
The GeoIP-based location of the device, on which the authentication activity is taking place, if available.
trusted_device
object
optional
A JSON object with further details on the user device involved in this authentication activity, if available (e.g. not all "passcode" factor types can be linked to a specific device). The table Trusted Device Information below describes the fields of this object.

Trusted Device Information

Fields
id
string
The ID of the user's mobile device involved in this authentication activity.
type
string
The type of device, for example: android or ios.
ip
string
optional
The IP address of the mobile device, if available.
location
string
optional
The GeoIP-based location location of the mobile device, if available.
display_name
string
The display name of this device.
app_version
string
The version of the Futurae mobile app running on this device, if applicable.

User Status

The user status is a string that represents the user's current status with respect to Futurae authentication. It will have one of the values described in the table below:

Values
bypass The user can bypass Futurae authentication. This implies that any Futurae authentication attempt for this user will automatically and immediately return allow.
enabled The user has one or more enrolled devices and must complete Futurae authentication using one of them.
disabled The user has no enrolled devices and Futurae authentication is disabled. The user cannot authenticate using Futurae authentication, before he enrolls a new device.
locked_out The user has been locked out due to an excessive amount of failed authentication attempts or his status was programmatically set to this value. This implies that any Futurae authentication attempt for this user will automatically and immediately return deny. His status needs to be reset (via Modify User) in order to be able to authenticate again using Futurae.
archived The user has been permanently deactivated.

Device

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

The Device resource is defined in the following table:

Example Device objects:

Mobile app device example:

{
    "capabilities": [
        "approve",
        "soundproof_jingle",
        "mobile_totp",
        "qr_code",
        "soundproof"
    ],
    "created_at": 1540997972,
    "device_id": "02286500-87c2-43da-9b32-d514a18500af",
    "display_name": "my google nexus 6P",
    "enrolled": true,
    "enrolled_at": 1540997973,
    "type": "android",
    "updated_at": 1543255887,
    "user_id": "70992f83-4543-11e7-89ab-c241ed9b4fdd",
    "version": "1.1.4",
    "version_supported": true
}

SMS device example:

{
    "capabilities": [
            "sms"
    ],
    "created_at": 1540998972,
    "device_id": "5bde7d1f-206b-4857-877d-f314912b83f0",
    "display_name": "My phone",
    "enrolled": false,
    "number": "+41123456789",
    "updated_at": 1543255887,
    "user_id": "70992f83-4543-11e7-89ab-c241ed9b4fdd",
    "sms_activation_code": "348728",
    "sms_code_expires_at": 1543256887
}
Fields
device_id
string
The ID of this device.
user_id
string
The ID of the user this device belongs to.
display_name
string
A short, memorable string which can be used to identify the device in a prompt. By default, the display name is the device model (or the phone number for SMS devices).
capabilities
[string]
A list of the available authentication technologies that can be used with this device. See Devices Capabilities for a detailed description.
enrolled
boolean
Indicates whether this device is enrolled or not.
enrolled_at
number
optional
The time when this device was enrolled, represented as a Unix timestamp.
created_at
number
The time when this device was created, represented as a Unix timestamp.
updated_at
number
The time when this device was last updated, represented as a Unix timestamp.
archived_at
number
optional
The time when this device was archived, represented as a Unix timestamp.
type
string
optional
Either android or ios. This field is only applicable for Futurae mobile app devices.
version
string
optional
The currently installed Futurae mobile app version. This field is only applicable for Futurae mobile app devices.
version_supported
boolean
optional
A boolean value indicating whether the currently installed mobile app version is supported by the currently operating version of the Futurae server. If this is false, then it means that the only functional capability of this device is mobile_totp. All other authentication factors will not be usable unless the user updates the mobile app. This field is only applicable for Futurae mobile app devices.
number
string
optional
The phone number of the device. This field is only applicable for SMS devices.
sms_activation_code
string
optional
The most recent activation code that was sent to the registered phone number in order to verify and activate this number for this user. This field is only applicable for SMS devices.
sms_code_expires_at
number
optional
The time when the SMS activation code expires, represented as a Unix timestamp. This field is only applicable for SMS devices.

Device Capabilities

Device capabilities are string values that represent which Futurae authentication technologies can be used with the specific device. The following table lists all the different device capabilities:

Values
approve The device supports authentication using approvals sent via push notifications (aka One-Touch).
mobile_totp The device can generate time-based one-time codes from within the Futurae mobile app.
qr_code The device supports authentication based on QR code scanning.
sms The device can receive SMS one-time codes.
soundproof The device can be used with SoundProof authentication (aka Zero-Touch).
soundproof_jingle The device can be used with Soundproof jingle-based authentication (aka Zero-Touch Jingle).

Enrollment

This resource represents a device enrollment and is defined in the following table:

Example Enrollment object:

{
    "activation_code": "CQJUlLMhG8Ox807lJMec1nHj2nfoPVBVBcoJSbH0qjs=",
    "activation_qrcode_url": "https://futurae.com/qr?enroll=CQJUlLMhG8Ox807lJMec1nHj2nfoPVBVBcoJSbH0qjs=",
    "created_at": 1503056849,
    "expires_at": 1503661649,
    "status": "pending",
    "updated_at": 1503056849,
    "user_id": "b91aa475-83f3-11e7-9a9d-0242ac120003"
}
Fields
activation_code
string
The activation code used for this enrollment. This field uniquely identifies an enrollment and is used as an ID.
activation_qrcode_url
string
The URL for an image of a scannable QR code that can be used to enroll a Futurae mobile app device.
user_id
string
The ID of the user this enrollment is associated with.
enrolled_device_id
string
optional
The ID of the Device that was enrolled using this enrollment.
expires_at
number
The time at which this enrollment will expire and will be no longer possible to enroll using it, represented as a Unix timestamp.
status
string
A string value indicating of the status of the enrollment, as specified in Enrollment Status.
success_callback_url
string
optional
The URL that the Futurae server will call in order to inform your application when the enrollment was successfully completed.
created_at
number
The time when this enrollment was created, represented as a Unix timestamp.
updated_at
number
The time when this enrollment was last updated, represented as a Unix timestamp.
archived_at
number
optional
The time when this enrollment was archived, represented as a Unix timestamp.

Enrollment Status

The enrollment status is a string that represents the status of a Futurae mobile app-based device enrollment. It will have one of the values described in the table below:

Values
success The enrollment has been completed successfully.
expired The enrollment has not been completed, and it has expired.
pending The enrollment has not been completed yet, and it is not yet expired.
archived The enrollment has been archived and can be no longer used or modified.

Aggregation

An aggregation object contains aggregated results according to the supplied aggregation parameters. Its format is specified in the table below:

Fields
group_by
string
The group_by parameter supplied in the query.
since
number
The since parameter supplied in the query.
until
number
The until parameter supplied in the query.
groups
[object]
A list of objects, which describe the stats for each one of the aggregation groups (time intervals). The statistics contained in each object depend on each individual endpoint that offers aggregated statistics. Each object contains statistics that correspond to the specific time interval. Additionally, each object contains a description of the time interval that the group corresponds to:

year — The year that this group corresponds to. Present for all aggregations.

month — The month that this group corresponds to. Present for aggregations grouped by month or day.

day — The day of the month that this group corresponds to. Present for aggregations grouped by day only.












© Copyright 2019 Futurae Technologies AG.