Back to top

Futurae Admin API Reference

Version 1.0.0

The Futurae Admin API provides functionality for managing the users of the Futurae Authentication suite and their two-factor authentication devices. 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 two-factor authentication and/or transaction signing capabilities to your website or application.

Version History (change log)

Getting Started

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

IMPORTANT NOTE: The Admin API key is different than the Auth API key, which is used to access the Auth API.

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

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.

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}

Request Authentication

In order to successfully call the API endpoints you need to authenticate your requests, by signing them using your Service Admin 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 Admin 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_Admin_API_Key, request_content)))

The signature is computed in exactly the same way as in the Auth API, with the only difference of using the Service Admin API key. Please refer to the respective Auth API section for detailed instructions and code snippets.

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

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/admin/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 Admin 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/admin/v1/server/api_version

Response  200

Request was successful.

Response Content

KeyDescription
api_version

Futurae Admin 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/admin/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/admin/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 the Service.

info

Get Service information
GET/info

Return Service information.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/info

Response  200

Request was successful.

Response Content

KeyDescription
name

The name of the Service.

description

The description of the Service.

Example Response

{
    "name": "Company",
    "description": "The Futurae service of the Company"
}

Users

Endpoints related to user management. The main resource that these endpoints target is the User record, and is defined in the following table.

Key Type Description
user_id string The user ID.
username string Username (either specified by the Service or randomly generated).
display_name string An optional display name for the user, which is displayed on the user’s Futurae mobile app.
allowed_factors [string] The list of the authentication factors that are permitted to be used for this user. See the list of available authentication factors.
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 is locked out.
service_defined_username boolean Indicates whether the user has been assigned a username from the service (true) or an automatically generated one (false).
status string A description of the status of the user. For more information, see the list of user status messages.
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 The time when this user was archived, represented as a Unix timestamp.

Available Authentication Factors

Factor Description
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 /users/{id}/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.

User Status

Name Description
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.
locked_out The user has been locked out due to an excessive amount of failed authentication attempts. The user’s status needs to be reset in order to be able to authenticate again.
disabled The user has no enrolled devices and secondary authentication is disabled. The user cannot authenticate using secondary authentication, before they enroll a device.
archived The user has been deactivated and can no longer authenticate.

users

Retrieve users
GET/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 the service will be matched.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/users?username=someuser%40domain.com&allowed_factors=approve%2Csoundproof&service_defined_username=true&status=&offset=0&limit=25&sort_by=username&order=asc

Request Query String Parameters

ParameterTypeRequiredDescription
username stringoptional

Lookup the user that has the supplied username.

Example: someuser@domain.com
allowed_factors stringoptional

A comma separated list of factors that must be (all) enabled. See the list of available authentication factors.

Example: approve,soundproof
service_defined_username booleanoptional

Filter based on whether the username was supplied by your application or instead was randomly chosen by Futurae.

Example: true
status stringoptional

Filter based on the user status.

Choices: bypass disabled enabled locked_out archived

offset numberoptional

Offset of first result (user record). Combined with limit it can be used to paginate the returned results.

Minimum: 0

Default: 0 
limit numberoptional

Maximum number of results (user records) to be returned. Combined with offset it can be used to paginate the returned results.

Minimum: 0 (no user records are returned, but the total number of records matching the filters, if any, can be retrieved)

Maximum: 100

Default: 25 
sort_by stringoptional

Sort the returned results by a specified field.

Choices: username status created_at updated_at

Default: created_at 
order stringoptional

Choose between ascending and descending order for sorting the returned results.

Choices: asc desc

Default: asc 

Response  200

Request was successful. The list of matching (or all) User records is returned.

Response Content

KeyDescription
limit

The supplied limit param.

offset

The supplied offset param.

count

The number of returned results (user records).

total

The total number of results that match the specified filters.

users

The list of matching User records.

Example Response

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

Response  400

Invalid parameters.

Example Response

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

Enroll new user
POST/users

This 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 mobile 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, the endpoint 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, the endpoint 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 (see the Auth API for more information).

Example URI

POST https://xxxxxx.futurae.com/srv/admin/v1/users

Request Body Parameters

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

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.

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

user

Retrieve user details
GET/users/{id}

Get details about the user with ID id.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/users/eb44cece-828e-11e7-bb14-c241ed9b4fdd

Response  200

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

Example Response

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

Response  404

The requested User resource does not exist.

Example Response

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

Modify user
PUT/users/{id}

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

Example URI

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

Request Body Parameters

ParameterTypeRequiredDescription
allowed_factors [string]optional

The list of the authentication factors that are permitted to be used for this user. See the list of available authentication factors.

Note that, the passcode factor 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 User status messages.

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.

Example Response

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

Response  304

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

Response  400

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

Example Response

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

Response  404

The requested user does not exist.

Example Response

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

Response  410

The specified user has already been archived.

Example Response

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

Deactivate user
DELETE/users/{id}

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

Example URI

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

Response  200

Request was successful. The specified user was removed.

Example Response

{
    "result": "ok"
}

Response  404

The requested user does not exist.

Example Response

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

Response  410

The specified user has already been archived.

Example Response

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

user devices

Retrieve user device details
GET/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.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/users/8dd64244-88d1-11e7-b00b-0242ac120003/devices?status=enrolled%2Cunenrolled

Request Query String Parameters

ParameterTypeRequiredDescription
status stringoptional

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.

Choices: enrolled, unenrolled, archived

Example: enrolled,unenrolled

Response  200

Request was successful.

Response Content

KeyDescription
count

The number of devices of the specified user, that are returned by this endpoint.

devices

The list of Device records that belong to the user.

Example Response

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

Response  404

The requested user does not exist.

Example Response

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

Enroll new user device
POST/users/{id}/devices

Initiate the enrollment of a new device for the user with ID id. When enrolling a new device, the same restrictions for the device attributes apply, as in POST /users.

Example URI

POST https://xxxxxx.futurae.com/srv/admin/v1/users/af6d33e2-7389-11e7-ac03-0242ac120003/devices

Request Body Parameters

ParameterTypeRequiredDescription
valid_secs numberoptional

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

Only applicable when enrolling a device with 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. 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 with 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.

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.

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.

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

Response  404

The specified user does not exist.

Example Response

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

Response  410

The specified user has already been archived.

Example Response

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

user enrollments

Retrieve user enrollment details
GET/users/{id}/enrollments

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

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/users/b91aa475-83f3-11e7-9a9d-0242ac120003/enrollments

Response  200

Request was successful.

Response Content

KeyDescription
count

The number of enrollments of the specified user, that are returned by this endpoint.

enrollments

The list of Enrollment records of the user.

Example Response

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

Response  404

The requested user does not exist.

Example Response

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

user backup codes

Retrieve user backup codes
GET/users/{id}/backup_codes

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

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/users/af6d33e2-7389-11e7-ac03-0242ac120003/backup_codes

Response  200

Request was successful.

Response Content

KeyDescription
backup_codes

The list of backup codes of the specified user. For every backup code, the following are returned:

ValueDescription
"code"

The backup code, formatted with spacing for readability.

"remaining_uses"

If the backup codes have been generated with a finite number of uses, this 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 value will be true; otherwise this will not be present.

Example Response

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

Response  404

The specified User ID does not exist.

Example Response

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

Generate a list of backup codes
POST/users/{id}/backup_codes

Clear the entire existing list of backup authentication codes and generate a new one, for the user with ID id. 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/admin/v1/users/af6d33e2-7389-11e7-ac03-0242ac120003/backup_codes

Request Body Parameters

ParameterTypeRequiredDescription
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 list of backup codes that were generated for the specified user. For every backup code, the following are returned:

ValueDescription
"code"

The backup code, formatted with spacing for readability.

"remaining_uses"

If the backup codes have been generated with a finite number of uses, this 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 value will be true; otherwise this will not be present.

Example Response

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

Response  400

Invalid parameters specified.

Example Response

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

Response  404

The requested user does not exist.

Example Response

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

Response  410

The specified user has already been archived.

Example Response

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

user one time code

Generate a new one-time code
POST/users/{id}/one_time_code

Generate a new random one-time code for the user with ID id. 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/admin/v1/users/7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6/one_time_code

Request Body Parameters

ParameterTypeRequiredDescription
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 parameters specified.

Example Response

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

Response  404

The requested user does not exist.

Example Response

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

Response  410

The specified user has already been archived.

Example Response

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

user activity

Retrieve recent user activity
GET/users/{id}/activity

Get details about the activity of the user with ID id. This endpoint retrieves at most 1000 user activity records, optionally limited by the since parameter (see below). The records are ordered by the activity timestamp, in descending order.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/users/eb44cece-828e-11e7-bb14-c241ed9b4fdd/activity?device_id=9c8a67bf-8bf1-11e7-b86c-0242ac120003&since=&limit=

Request Query String Parameters

ParameterTypeRequiredDescription
device_id stringoptional

The ID of a specific device of the user, to query activity for.

Example: 9c8a67bf-8bf1-11e7-b86c-0242ac120003
since numberoptional

The time since when to retrieve user activity, represented as a Unix timestamp.

Minimum: 0

**Default:** 0
limit numberoptional

The maximum number of records to return.

Minimum: 1

Maximum: 1000

Default: 1000

Response  200

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

Response Content

KeyDescription
count

The number of user activity records returned.

activity

The list of user activity records, as a JSON array. Each record contains the following attributes.

KeyDescription
user_id

The ID of the user.

device_id

The ID of the device that the user activity was recorded from. This is present only where applicable (e.g. not all “passcode” factor types can be linked to a device).

timestamp

The time at which the user activity record occurred, represented as a Unix timestamp.

details

A JSON object with further details on the user activity record:

KeyDescription
factor

The authentication factor used for this record. This is not present when the activity record describes an event of 2FA-bypass, 2FA-disabled, user locked-out, or a trusted device token.

result

The result of the authentication for this user activity. For example:

ValueDescription
"allow"

The authentication attempt was allowed.

"deny"

The authentication attempt was denied.

reason

Further information on the authentication result. 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”).

device_type

The type of device, if this record is linked to one, for example: “android”, “ios”.

backend_ip

The IP address of the backend server of your application that issued the authentication request to the Futurae server (where applicable).

browser_ip

The IP address of the browser client, on which the authentication activity is taking place (where applicable).

mobile_ip

The IP address of the mobile client, i.e., the user’s mobile phone, involved in the authentication activity (where applicable).

Example Response

{
    "activity": [
        {
            "details": {
                "result": "allow",
                "reason": "trusted_token"
            },
            "timestamp": 1503927048,
            "user_id": "9c87d983-8bf1-11e7-b86c-0242ac120003"
        },
        {
            "details": {
                "factor": "passcode",
                "result": "deny",
                "reason": "one_time_code expired"
            },
            "timestamp": 1503925601,
            "user_id": "9c87d983-8bf1-11e7-b86c-0242ac120003"
        },
        {
            "details": {
                "factor": "soundproof",
                "result": "allow",
                "device_type": "android"
            },
            "device_id": "9c8a67bf-8bf1-11e7-b86c-0242ac120003",
            "timestamp": 1503925553,
            "user_id": "9c87d983-8bf1-11e7-b86c-0242ac120003"
        }
    ],
    "count": 3
}

Response  400

Invalid parameters.

Example Response

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

Response  404

The requested user does not exist.

Example Response

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

Devices

Endpoints related to device management. The main resource that these endpoints target is the Device record, In general, we differentiate between two types of devices:

  • A device that has the Futurae Mobile app installed, called Mobile app device. These devices can support and offer the mobile app-based secondary authentication factors, such as “soundproof”, “approve” and “mobile_totp”.

  • A device that is associated with a phone number, called SMS device. SMS devices only have the “sms” capability and can be used to send SMS one-time codes (“sms” factor).

The Device record is defined in the following table.

Key Type Description
device_id string The ID of the device.
user_id string The ID of the user this device belongs to.
capabilities [string] The list of the available factors that can be used with this device. For more information, see the list of available authentication factors.
display_name string A short, memorable string which can be used to identify the device in a prompt.
enrolled boolean Indicates this device is enrolled or not.
enrolled_at number 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 The time when this device was archived, represented as a Unix timestamp.
type string Either “android” or “ios”. Only applicable for Mobile app devices.
version string The currently installed Futurae mobile app version. Only applicable for Mobile app devices.
version_supported boolean Indicates 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”. All other factors will not be usable unless the user updates the mobile app. Only applicable for Mobile app devices.
number string The phone number of the device. Only applicable for SMS devices.
sms_activation_code string The most recent activation code that was sent to the registered phone number in order to verify and enroll this number for this user. Only applicable for SMS devices.
sms_code_expires_at number The time when the SMS activation code expires, represented as a Unix timestamp. Only applicable for SMS devices.

devices

Enroll new device
POST/devices

Initiate the enrollment of a new device for an existing user. This endpoint is identical to POST /users/{id}/devices. 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.

For more information, see the POST /users/{id}/devices endpoint.

Example URI

POST https://xxxxxx.futurae.com/srv/admin/v1/devices

Request Body Parameters

ParameterTypeRequiredDescription
user_id stringrequired

The ID of the user to enroll a new device for.

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

device

Retrieve device details
GET/devices/{id}

Get details about the device with ID id.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/devices/af799248-7389-11e7-ac03-0242ac120003

Response  200

Request was successful. The Device record that describes the specified device is returned.

Example Response

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

Response  404

The specified device ID does not exist.

Example Response

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

Modify device details
PUT/devices/{id}

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

Example URI

PUT https://xxxxxx.futurae.com/srv/admin/v1/devices/af799248-7389-11e7-ac03-0242ac120003

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

{
    "display_name": "new display name"
}

Response  304

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

Response  404

The specified device ID does not exist.

Example Response

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

Response  410

The specified device has already been archived.

Example Response

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

Unenroll user device
DELETE/devices/{id}

Unenroll (archive) 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

DELETE https://xxxxxx.futurae.com/srv/admin/v1/devices/af799248-7389-11e7-ac03-0242ac120003

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  404

The specified device ID does not exist.

Example Response

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

Response  410

The specified device has already been archived.

Example Response

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

Enrollments

Endpoints related to enrollment management. The main resource that these endpoints target is the Enrollment record, and is defined in the following table.

Key Type Description
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 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 description of the status of the enrollment. For more information, see the list of enrollment status messages.
success_callback_url string 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 The time when this enrollment was archived, represented as a Unix timestamp.

Enrollment Status

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

enrollments

Retrieve enrollments
GET/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.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/enrollments?user_id=&enrolled_device_id=&created_since=&created_until=&expires_since=&expires_until=&status=&offset=0&limit=25&sort_by=status&order=asc

Request Query String Parameters

ParameterTypeRequiredDescription
user_id stringoptional

Filter on the UserID of an enrollment.

enrolled_device_id stringoptional

Filter on the DeviceID that got enrolled with this enrollment.

created_since numberoptional

Search for enrollments created since the specified timestamp (represented as a Unix timestamp).

Minimum: 0

created_until numberoptional

Search for enrollments created until the specified timestamp (represented as a Unix timestamp).

Minimum: 0

expires_since numberoptional

Search for enrollments that expire since the specified timestamp (represented as a Unix timestamp).

Minimum: 0

expires_until numberoptional

Search for enrollments that expire until the specified timestamp (represented as a Unix timestamp).

Minimum: 0

status stringoptional

Filter based on the enrollment status. For more information, see the Enrollment Status description.

Choices: pending expired success archived

offset numberoptional

Offset of first result (enrollment record). Combined with limit it can be used to paginate the returned results.

Minimum: 0

Default: 0 
limit numberoptional

Maximum number of results (enrollment records) to be returned. Combined with offset it can be used to paginate the returned results.

Minimum: 0 (no enrollment records are returned, but the total number of records matching the filters, if any, can be retrieved)

Maximum: 100

Default: 25 
sort_by stringoptional

Sort the returned results by a specified field.

Choices: created_at expires_at status user_id

Default: created_at 
order stringoptional

Choose between ascending and descending order for sorting the returned results.

Choices: asc desc

Default: asc 

Response  200

Request was successful. The list of matching (or all) User records is returned. Note that the enrolled_device_id field will be missing in case the enrollment has not (yet) been completed. Similarly, the archived_at field will only exist if the enrollment has been archived.

Response Content

KeyDescription
limit

The supplied limit param.

offset

The supplied offset param.

count

The number of returned results (enrollment records).

total

The total number of results that match the specified filters.

enrollments

The list of matching Enrollment records.

Example Response

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

Response  400

Invalid parameters.

Example Response

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

enrollment

Retrieve enrollment details
GET/enrollments/{id}

Retrieve the details of the enrollment with Activation Code id.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/enrollments/G4nSSly7nLmrZ1pVpD1C2FzO0wmJzzjy9z3pFSqYdyU=

Response  200

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

Example Response

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

Response  404

The specified enrollment does not exist.

Example Response

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

Modify enrollment details
PUT/enrollments/{id}

Modify attributes of the enrollment with Activation Code id. The attributes that can be modified are shown in the table below; for more information on the attributes, see the Enrollment resource.

Example URI

PUT https://xxxxxx.futurae.com/srv/admin/v1/enrollments/CQJUlLMhG8Ox807lJMec1nHj2nfoPVBVBcoJSbH0qjs=

Request Body Parameters

ParameterTypeRequiredDescription
expires_at numberrequired

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. status = 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 stringrequired

The URL to be used for the success callback. It is not possible to update this attribute for completed or archived enrollments.

Response  200

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

Example Response

{
    "expires_at": 1503056850
}

Response  304

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

Response  404

The specified enrollment does not exist.

Example Response

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

Response  410

The specified enrollment has already been archived or completed.

Example Response

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

Invalidate enrollment
DELETE/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 using PUT /enrollments/{id}.

Example URI

DELETE https://xxxxxx.futurae.com/srv/admin/v1/enrollments/CQJUlLMhG8Ox807lJMec1nHj2nfoPVBVBcoJSbH0qjs=

Response  200

Request was successful.

Example Response

{
    "result": "ok"
}

Response  404

The specified enrollment does not exist.

Example Response

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

Response  410

The specified enrollment has already been archived.

Example Response

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

Statistics

users stats

Users Statistics
GET/stats/users

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

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/stats/users?since=1504224000&until=1506729600&group_by=month

Request Query String Parameters

ParameterTypeRequiredDescription
since unix timestampoptional

Time since when to fetch stats.

Default: Beginning of current month.

Minimum: 30 days in the past.

Example: 1504224000
until unix timestampoptional

Time until when to fetch stats.

Default: End of current month.

Maximum: End of current month.

Example: 1506729600
group_by stringoptional

Optionally group the statistics by year, month, or day.

Choices: year, month, day

Default: month

Example: month

Response  200

Successful request; the statistics overview is returned in a single JSON response object.

Response Content

KeyDescription
total

The total number of users of the service.

2fa_bypass

The number of users configured to bypass two-factor authentication.

2fa_enabled

The number of users for which two-factor authentication is enabled.

2fa_disabled

The number of users for which two-factor authentication is disabled.

locked_out

The number of users that due to a large number of failed authentication attempts, have been locked out.

aggregation

This object contains the aggregated results according to the query parameters.

KeyDescription
group_by

The grouping parameter repeated.

since

The since parameter repeated.

until

The until parameter repeated.

groups

A list of objects, which describe the stats of each one of the aggregation groups. Each object contains statistics for all the values that also exist at the top level, and that correspond to this specific time group. Additionally, each object contains a description of the time that the group corresponds to:

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

Example Response

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

Response  400

Invalid parameters.

Example Response

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

active users stats

Active Users Statistics
GET/stats/users/active

Retrieve active User statistics, limited and aggregated by the requested period.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/stats/users/active?since=1504224000&until=1506729600&group_by=month

Request Query String Parameters

ParameterTypeRequiredDescription
since unix timestampoptional

Time since when to fetch stats.

Default: Beginning of current month.

Minimum: 30 days in the past.

Example: 1504224000
until unix timestampoptional

Time until when to fetch stats.

Default: End of current month.

Maximum: End of current month.

Example: 1506729600
group_by stringoptional

Optionally group the statistics by year, month, or day.

Choices: year, month, day

Default: month

Example: month

Response  200

Successful request; the statistics are returned in a single json response object.

Response Content

KeyDescription
aggregation

This object contains the aggregated results according to the query parameters.

KeyDescription
group_by

The grouping parameter repeated.

since

The since parameter repeated.

until

The until parameter repeated.

groups

A list of objects, which describe the stats of each one of the aggregation groups. Additionally, each object contains a description of the time that the group corresponds to:

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

"active"

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

Example Response

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

Response  400

Invalid parameters.

Example Response

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

activity stats

Activity Statistics
GET/stats/activity

Retrieve User Activity statistics, limited and aggregated by the requested period.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/stats/activity?since=1504224000&until=1506729600&group_by=month

Request Query String Parameters

ParameterTypeRequiredDescription
since unix timestampoptional

Time since when to fetch stats.

Default: Beginning of current month.

Minimum: 30 days in the past.

Example: 1504224000
until unix timestampoptional

Time until when to fetch stats.

Default: End of current month.

Maximum: End of current month.

Example: 1506729600
group_by stringoptional

Optionally group the statistics by year, month, or day.

Choices: year, month, day

Default: month

Example: month

Response  200

Successful request; the statistics overview is returned in a single json response object.

Response Content

KeyDescription
aggregation

This object contains the aggregated results according to the query parameters.

KeyDescription
group_by

The grouping parameter repeated.

since

The since parameter repeated.

until

The until parameter repeated.

groups

A list of objects, which describe the stats of each one of the aggregation groups. Additionally, each object contains a description of the time that the group corresponds to:

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

2fa_allowed

The total number of successful 2FA attempts.

2fa_denied

The total number of unsuccessful 2FA attempts.

bypass

The number of attempts that were allowed due to 2FA 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 list of JSON objects with statistics broken down for each factor used.

KeyDescription
<factor>

The name of the authentication factor.

ValueDescription
"allowed"

The number of successful attempts.

"denied"

The number of unsuccessful attempts.

Example Response

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

Response  400

Invalid parameters.

Example Response

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

devices stats

Devices Statistics
GET/stats/devices

Retrieve User Devices statistics, limited and aggregated by the requested period.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/stats/devices

Response  200

Successful request; the statistics overview is returned in a single json response object.

Response Content

KeyDescription
total

The total number of enrolled devices.

ios, android

Statistics for iOS/Android devices.

ValueDescription
"<version>"

The number of devices at the specified app version (“n/a” if the version is not available).

sms

The number of SMS devices.

aggregation

This object contains the aggregated results according to the query parameters.

KeyDescription
group_by

The grouping parameter repeated.

since

The since parameter repeated.

until

The until parameter repeated.

groups

A list of objects, which describe the stats of each one of the aggregation groups. Each object contains statistics for all the values that also exist at the top level, and that correspond to this specific time group. Additionally, each object contains a description of the time that the group corresponds to:

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

Example Response

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

Response  400

Invalid parameters.

Example Response

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

enrollments stats

Enrollments Statistics
GET/stats/enrollments

Retrieve Enrollment statistics. The statistics return correspond to the total numbers of enrollments in the system.

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/stats/enrollments

Response  200

Successful request; the statistics overview is returned in a single json response object.

Response Content

KeyDescription
total

The total number of enrollments of the service.

pending

The number of pending enrollments.

success

The number of enrollments that have been successfully completed.

expired

The number of enrollments that have already expired without having been completed.

Example Response

{
    "expired": 20,
    "pending": 1,
    "success": 268,
    "total": 289
}

Response  400

Invalid parameters.

Example Response

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

geo stats

GeoIP statistics overview
GET/stats/geo

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

Example URI

GET https://xxxxxx.futurae.com/srv/admin/v1/stats/geo?since=1504224000&until=1506729600

Request Query String Parameters

ParameterTypeRequiredDescription
since unix timestampoptional

Time since when to fetch stats.

Default: Beginning of current month.

Minimum: 30 days in the past.

Example: 1504224000
until unix timestampoptional

Time until when to fetch stats.

Default: End of current month.

Maximum: End of current month.

Example: 1506729600

Response  200

The request was successful, and the GeoIP statistics overview is returned.

Response Content

KeyDescription
login_dev_iso_country, trusted_dev_iso_country

A list of ISO Country Codes and count of IPs with recorded activity for the requested timeframe, that correspond to the IP of the device used for the login (typically a web browser) and to the IP of the trusted device used (typically a mobile app). The since and until parameters are repeated to describe exactly the time period of the statistics.

KeyDescription
total

The total number of IPs with recorded activity.

<country>

The number of IPs with recorded activity for the respective country. (e.g. “CH”, “IT”, “GR”, etc).

ValueDescription
"total"

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

"success"

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

Example Response

{
    "login_dev_iso_country": {
        "CH": {
            "success": 22,
            "total": 23
        },
        "total": 23
    },
    "since": 1504224000,
    "trusted_dev_iso_country": {
        "CH": {
            "success": 87,
            "total": 90
        },
        "total": 90
    },
    "until": 1506815999
}

Response  400

Invalid parameters.

Example Response

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

© Copyright 2017 Futurae Technologies AG.

Generated by aglio on 15 Nov 2017