NAV

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

Version History (change log)

Getting Started

The Futurae Admin API operates on Futurae Services. A Futurae Service represents one of your end-user applications (or a set of applications, if they are all using the same user Identity Database), which is to be protected with Futurae authentication. The end users of your application must be enrolled in the corresponding Futurae Service, thereby creating a mapping of your end users into Futurae, which we call Futurae users.

Each Service belongs to an Organization in Futurae Admin. Refer to this article to learn more about managing Services and Organizations in Futurae Admin.

In order to be able to use the Admin API you will need to get your Service credentials: Service ID, Admin API key and Service hostname (which is the host part of the Service Base URL). Additionally, you can use the Callback Signature key to verify callback signatures. You can get these credentials from Futurae Admin.

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

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

Postman Sample Collection

To help you with integration, we provide a postman collection with a few sample Admin API endpoints.

Once you import the collection into Postman, you will need to edit it and adjust the following variables:

Variable Value
hostname Your Service Hostname (example: api.futurae.com)
service_id Your Service ID
admin_api_key Your Admin API key

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

Callback Authentication

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

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

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

JWS Signatures

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

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

x-jws-signature: eyJhbGciOiJIUzI1NiJ9..NsolKSrrFivUFZx_qixwfrogkrpdkz54QyiWlosngwQ

To verify the JWS signature, perform the following steps:

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

eyJhbGciOiJIUzI1NiJ9.base64url(HTTP_request_body).NsolKSrrFivUFZx_qixwfrogkrpdkz54QyiWlosngwQ

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

Response Format

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

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

This is how an unsuccessful response payload looks like:

{
    "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
string
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
string
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
string
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,
    "accounts_migration_callback_url": "https://www.domain.com/callback",
    "session_timeout": 90
}

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.
accounts_migration_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the accounts migration was successfully completed.
session_timeout
number
optional
Used to set the default timeout in seconds that is applied to all authentication or transaction signing sessions, created for the specific Service.
Minimum: 30
Maximum: 120
Default: 60

Update Service Information

Update Service information.

PUT /srv/admin/v1/info

Body Parameters

Example request body params:

{
  "accounts_migration_callback_url": "https://www.domain.com/callback",
  "session_timeout": 90
}
accounts_migration_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the accounts migration 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, device_id, migrated_to_device_id and migrated_at. There will be one callback for each of the migrated accounts, each with its own device_id, migrated_to_device_id pair.
The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443.
session_timeout
number
optional
A number that indicates the session timeout value in seconds. If omitted the value will not be updated.
Minimum: 30
Maximum: 120

Response 200

Example response:

200 OK
{
    "accounts_migration_callback_url": "https://www.domain.com/callback",
    "session_timeout": 90
}

Request was successful.

Fields
accounts_migration_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the accounts migration was successfully completed.
session_timeout
number
optional
A number that indicates the default timeout to be used on authentication requests of the service.

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, for example accounts_migration_callback_url is not a string.

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&until=1537180000&offset=0&limit=100&factor=approve&result=deny&reason=&type=Login&location=CH
since
number
optional
The time since when to retrieve user activity, represented as a Unix timestamp.
Minimum: 1 month in the past.
Default: Beginning of current month.
until
number
optional
The time until 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
factor
string
optional
The authentication factor to filter records on. 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
optional
The result of the authentication to filter records on. Either allow or deny.
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). The empty string can also be used to filter for records with no reason specified (&reason=).
type
string
optional
The type of authentication to filter records on (e.g., Login, Transaction).
location
string
optional
The GeoIP-based location to filter records on, specified by the ISO code of the country (e.g. location=ch).

Response 200

Example response:

200 OK
{
    "activity": [
        {
            "backend_ip": "172.18.0.1",
            "factor": "approve",
            "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.

Get Active Users

GET /srv/admin/v1/active_users

Get a list of the active users of the Service.

This endpoint retrieves all active users of the Service, formatted in individual user 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 user records returned are ordered by their last_active_at timestamp.

Query Parameters

Example request query params:

since=1537170000&until=1537180000&offset=0&limit=100&order=asc
since
number
optional
Time since when to retrieve active users (Unix timestamp).
Default: Beginning of current month.
Minimum: 2 years in the past.
until
number
optional
Time until when to retrieve active users (Unix timestamp).
Default: End of current month.
Maximum: End of current month.
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
order
string
optional
Choose between ascending (asc) and descending (desc) order for sorting the returned results.
Default: asc

Response 200

Example response:

200 OK
{
    "count": 1,
    "limit": 100,
    "offset": 0,
    "total": 1,
    "users": [
        {
            "allowed_factors": [
                "approve",
                "mobile_totp",
                "passcode",
                "qr_code",
                "sms"
            ],
            "created_at": 1496154161,
            "failed_attempts": 0,
            "max_attempts": 15,
            "service_defined_username": true,
            "status": "enabled",
            "last_active_at": "2019-05-23 00:00:00",
            "updated_at": 1500361673,
            "user_id": "70992f83-4543-11e7-89ab-c241ed9b4fdd",
            "username": "user@domain.com"
        }
    ]
}

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.
since
number
The since param.
until
number
The until param.
limit
number
The limit param.
offset
number
The offset param.
users
[object]
The list of User records, as a JSON array. The record will additionally contain the last_active_at field.

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%2Cqr_code&service_defined_username=true&offset=0&limit=25&sort_by=username&order=asc
username
string
optional
Filter based on whether the User username attribute contains the supplied value.
This is partial match operation. To ensure that the lookup always returns a single user with an exactly matching username (if such a user exists), you should construct the user usernames such that no username is contained in another username (examples: UUID strings, or any other fixed-length alphanumeric identifiers).
display_name
string
optional
Filter based on whether the User display name attribute contains the supplied value.
This is a partial match and case-insensitive search operation.
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, display_name, created_at, updated_at
Default: created_at
order
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"  
            ],
            "created_at": 1496154161,
            "failed_attempts": 0,
            "max_attempts": 15,
            "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"                
            ],
            "created_at": 1496167403,
            "display_name": "otheruser@domain.com",
            "failed_attempts": 0,
            "max_attempts": 15,
            "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 several distinct enrollment cases, depending on the type of device.

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 mobile device for this user. In particular, this endpoint invocation will return an activation code as a QR code PNG image (also as a clickable URI) that the Futurae mobile app can scan using the mobile device's built-in camera. Scanning the QR code activates the particular device for the specific user.

Body Parameters

Example request body params:

{
    "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. If not supplied, the display name will be empty.
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)
short_code
boolean
optional
Set this field to true if you require a short activation code to be included in the response. A short activation code is suitable for manual user entry in the app, and is useful in case the user's phone has a malfunctioning camera or if the user does not want to give the app permission to access the camera.
Default: false
success_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. This is an alternative to using Auth API's Enroll Status The URL will be called as a POST request with Content-Type header being application/json. The body of the request will be a JSON object containing the following fields and corresponding values: user_id, username, activation_code, device_id and result. The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.
The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443.

Response 200

Example response:

200 OK
{
  "activation_code": "MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_code_uri": "futurae://enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
  "activation_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?enroll=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "expiration": 1461694259,
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "username": "someuser@domain.com"
}

Request was successful.

Fields
activation_code
string
The activation code.
activation_qrcode_url
string
URL for a PNG image of a scannable QR code with the activation code. This is useful when the user attempts to enable Futurae authentication by accessing his account from a device different than the one on which the Futurae mobile app is installed, for example, when accessing his account from a desktop/laptop computer. Note that the URL is directly accessible (i.e., no Authorization header needed).
activation_qrcode_data_uri
string
PNG image of a scannable QR code containing the activation code in data URI scheme. This is the same QR code image that can be retrieved via activation_qrcode_url.
activation_code_uri
string
The activation code in the form of a URI prefixed with the SDK/app scheme, this would be futurae:// for the Futurae mobile app. 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).
activation_code_short
string
If short_code was set to true, then this field contains the short activation code, suitable for manual user entry. Otherwise this field is not contained in the response.
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 FIDO Device

POST /srv/admin/v1/users

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

Body Parameters

Example request body params:

{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "fido": true,
    "valid_secs": 3600,
    "authenticator_selection": {
        "user_verification": "required"
    },
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity"
}
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. If not supplied, the display name will be empty.
See the input restrictions that apply.
fido
boolean
required
This field must be set to true, in order to enroll a FIDO device.
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)
short_code
boolean
optional
Set this field to true if you require a short activation code to be included in the response. A short activation code is suitable for delivering to the user and requiring them to supply it during the FIDO registration process (as explained in the explicit approach above).
Default: false
attestation_preference
string
optional
Supply this field to override the Relying Party's default Attestation Conveyance Preference. Refer to the WebAuthn RP Configuration resource for a detailed description.
authenticator_selection
object
optional
Supply this field to override the Relying Party's default Authenticator Selection Criteria. Refer to the WebAuthn RP Configuration resource for a detailed description.
success_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. This is an alternative to using Auth API's Enroll Status. The URL will be called as a POST request with Content-Type header being application/json. The body of the request will be a JSON object containing the following fields and corresponding values: user_id, username, activation_code, device_id and result. The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.
The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443.

Response 200

Example response:

200 OK
{
    "activation_code": "NUhiSXk4eF9LRVE3SXdFZDZvRmVUeFd4Qy1BWGtPUlJZX1JnM0ctZm1EQWk6N2E3ZjUyMDktZWUwOS00ZDU0LThlYzAtY2Y2MTAyYjVmNGI2OmFwaS10ZXN0LmZ1dHVyYWUuY29t",
    "activation_code_short": "vr50 7gia qpsi qg8e",
    "expiration": 1461694259,
    "user_id": "7a7f5209-ee09-4d54-8ec0-cf6102b5f4b6",
    "username": "someuser@domain.com"
}

Request was successful.

Fields
activation_code
string
The activation code. Suitable for use in the implicit approach explained above.
activation_code_short
string
If short_code was set to true, then this field contains the short form of the activation code, otherwise this field is not contained in the response. The short activation code is suitable for the explicit approach explained above.
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.

Response 403

Example response:

403 Forbidden
{
    "error": true,
    "code": 40300,
    "message": "forbidden"
}

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

Enroll New User with Hardware Token

POST /srv/admin/v1/users

Create a new user in Futurae and at the same time assign a hardware Token to them. The assignment creates a new device record for this user.

Body Parameters

Example request body params:

{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10"
}
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. If not supplied, the display name will be empty.
See the input restrictions that apply.
hwtoken_id
string
required
The ID of the Hardware Token that will be enrolled for this user.
hwtoken_passcode
string
optional
If hwtoken_id is a TOTP hardware token, you can optionally supply the current TOTP value for verification. If a TOTP value is indeed supplied and verification fails, then this enrollment will not succeed.

This is useful in case the TOTP token enrollment process is delegated to the end users themselves. In such a case, you can ask the user to supply the current value of the TOTP token they are attempting to enroll for themselves, in order to verify that they indeed have access to the claimed token.

Response 200

Example response:

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

Request was successful.

Fields
device_id
string
The ID of the newly created hardware token device.
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"
}

Example response (TOTP verification failed):

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

Request failed. One of the following reasons apply:

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. If not supplied, the display name will be empty.
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 SMS 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 403

Example response:

403 Forbidden
{
  "error": true,
  "code": 40303,
  "message": "no SMS sender name set"
}

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

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"
    ],
    "created_at": 1502893600,
    "display_name": "my display name",
    "failed_attempts": 0,
    "max_attempts": 15,
    "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", "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.
A value of 15 (which is the default value) means that the user will be locked out on the 16th consecutive failed attempt.
The default value can be configured per each Futurae Service in Futurae Admin (newly created users will have the specified default value).
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.

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.

Query Parameters

Example request query params:

status=enrolled,archived&type=android
status
string
optional
A comma-separated list of status strings of devices to return. The available values are enrolled, unenrolled and archived.
type
string
optional
A comma-separated list of the types of devices to return. The available values are android, ios, hwtoken and sms.

Response 200

Example response:

200 OK
{
    "count": 1,
    "devices": [
        {
            "capabilities": [
                "mobile_totp",
                "approve",
                "qr_code"
            ],
            "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 several distinct enrollment cases, depending on the type of device.

Enroll New Mobile App

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

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

Body Parameters

Example request body params:

{
    "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)
short_code
boolean
optional
Set this field to true if you require a short activation code to be included in the response. A short activation code is suitable for manual user entry in the app, and is useful in case the user's phone has a malfunctioning camera or if the user does not want to give the app permission to access the camera.
Default: false
success_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. This is an alternative to using Auth API's Enroll Status. The URL will be called as a POST request with Content-Type header being application/json. The body of the request will be a JSON object containing the following fields and corresponding values: user_id, username, activation_code, device_id and result. The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.
The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443.

Response 200

Example response:

200 OK
{
  "activation_code": "MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_code_uri": "futurae://enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
  "activation_qrcode_url": "https://api.futurae.com/srv/auth/v1/qr?enroll=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "expiration": 1461694259,
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "username": "someuser@domain.com"
}

Request was successful.

Fields
activation_code
string
The activation code for this enrollment.
activation_qrcode_url
string
URL for a PNG image of a scannable QR code with the activation code. This is useful when the user attempts to enable Futurae authentication by accessing his account from a device different than the one on which the Futurae mobile app is installed, for example, when accessing his account from a desktop/laptop computer. Note that the URL is directly accessible (i.e., no Authorization header needed).
activation_qrcode_data_uri
string
PNG image of a scannable QR code containing the activation code in data URI scheme. This is the same QR code image that can be retrieved via activation_qrcode_url.
activation_code_uri
string
The activation code in the form of a URI prefixed with the SDK/app scheme, this would be futurae:// for the Futurae mobile app. 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).
activation_code_short
string
If short_code was set to true, then this field contains the short activation code, suitable for manual user entry. Otherwise this field is not contained in the response.
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 FIDO Device

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

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

Body Parameters

Example request body params:

{
    "fido": true,
    "valid_secs": 3600,
    "authenticator_selection": {
        "user_verification": "required"
    },
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity"
}
fido
boolean
required
This field must be set to true, in order to enroll a FIDO device.
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)
short_code
boolean
optional
Set this field to true if you require a short activation code to be included in the response. A short activation code is suitable for delivering to the user and requiring them to supply it during the FIDO registration process (as explained in the explicit approach above).
Default: false
attestation_preference
string
optional
Supply this field to override the Relying Party's default Attestation Conveyance Preference. Refer to the WebAuthn RP Configuration resource for a detailed description.
authenticator_selection
object
optional
Supply this field to override the Relying Party's default Authenticator Selection Criteria. Refer to the WebAuthn RP Configuration resource for a detailed description.
success_callback_url
string
optional
A URL that the Futurae server can call in order to inform your application when the enrollment was successfully completed. This is an alternative to using Auth API's Enroll Status. The URL will be called as a POST request with Content-Type header being application/json. The body of the request will be a JSON object containing the following fields and corresponding values: user_id, username, activation_code, device_id and result. The value of the latter will always be "success", since the callback will only be called when the enrollment is completed successfully.
The supplied URL must be https (certificate issued by a publicly acceptable CA), FQDN (no IP address) and to port 443.

Response 200

Example response:

200 OK
{
    "activation_code": "NUhiSXk4eF9LRVE3SXdFZDZvRmVUeFd4Qy1BWGtPUlJZX1JnM0ctZm1EQWk6N2E3ZjUyMDktZWUwOS00ZDU0LThlYzAtY2Y2MTAyYjVmNGI2OmFwaS10ZXN0LmZ1dHVyYWUuY29t",
    "activation_code_short": "vr50 7gia qpsi qg8e",
    "expiration": 1461694259,
    "user_id": "7a7f5209-ee09-4d54-8ec0-cf6102b5f4b6",
    "username": "someuser@domain.com"
}

Request was successful.

Fields
activation_code
string
The activation code. Suitable for use in the implicit approach explained above.
activation_code_short
string
If short_code was set to true, then this field contains the short form of the activation code, otherwise this field is not contained in the response. The short activation code is suitable for the explicit approach explained above.
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 403

Example response:

403 Forbidden
{
    "error": true,
    "code": 40300,
    "message": "forbidden"
}

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

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 Hardware Token

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

Assign a hardware Token to the specified Futurae user id. The assignment creates a new device record for this user.

Body Parameters

Example request body params:

{
    "hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10"
}
hwtoken_id
string
required
The ID of the Hardware Token that will be enrolled for this user.
hwtoken_passcode
string
optional
If hwtoken_id is a TOTP hardware token, you can optionally supply the current TOTP value for verification. If a TOTP value is indeed supplied and verification fails, then this enrollment will not succeed.

This is useful in case the TOTP token enrollment process is delegated to the end users themselves. In such a case, you can ask the user to supply the current value of the TOTP token they are attempting to enroll for themselves, in order to verify that they indeed have access to the claimed token.

Response 200

Example response:

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

Request was successful.

Fields
device_id
string
The ID of the newly created hardware token device.
user_id
string
Permanent, unique identifier for the user in Futurae. Always generated by Futurae.
username
string
Unique identifier for the user in Futurae. Either specified as a parameter upon user creation or auto-generated.

Response 400

Example response:

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

Example response (TOTP verification failed):

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

Request failed. One of the following reasons apply:

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, for the specified Futurae user id, 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 SMS 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 403

Example response:

403 Forbidden
{
  "error": true,
  "code": 40303,
  "message": "no SMS sender name set"
}

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

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_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
            "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_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
            "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: 604800 (7 days)
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.

Query Parameters

Example request query params:

since=1537170000&offset=0&limit=100&order=desc
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: 1 month in the past.
Default: The beginning of current month.
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
order
string
optional
Choose between ascending (asc) and descending (desc) order for sorting the returned results.
Default: asc

Response 200

Example response:

200 OK
{
    "activity": [
        {
            "backend_ip": "172.18.0.1",
            "factor": "approve",
            "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.

Get List of Devices

GET /srv/admin/v1/devices

Query the list of devices of the service, including a set of filters and pagination parameters. The devices returned are sorted by their enrolled_at timestamp.

Query Parameters

Example request query params:


type=android&status=enrolled&since=1555078597&until=1556552508&offset=10&limit=100&order=desc
type
string
optional
A comma-separated list of the types of devices to return. The available values are android, ios, hwtoken and sms.
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.
since
number
optional
Time since when to fetch devices (Unix timestamp).
Default: Beginning of current month.
Minimum: 2 years in the past.
until
number
optional
Time until when to fetch devices (Unix timestamp).
Default: End of current month.
Maximum: End of current month.
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
order
string
optional
Choose between ascending (asc) and descending (desc) order for sorting the returned results.
Default: desc

Response 200

Example response:

200 OK
{
    "count": 1,
    "devices": [
        {
            "capabilities": [
                "approve",
                "mobile_totp",
                "qr_code"
            ],
            "created_at": 1556797427,
            "device_id": "5f953475-3bcf-4fcc-aa5d-4e4e7411d77b",
            "display_name": "OnePlus ONEPLUS A3003",
            "enrolled": true,
            "enrolled_at": 1556797427,
            "type": "android",
            "updated_at": 1556797428,
            "user_id": "d811b2e8-4b53-4507-aef1-1ec4ae76d625",
            "version": "1.2.1",
            "version_supported": true
        }
    ],
    "limit": 25,
    "offset": 0,
    "total": 1
}

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.
devices
[object]
The list of Device records, as a JSON array.

Response 400

Example response:

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

Invalid parameters.

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"
    ],
    "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, for Futurae mobile app devices the display name is the device model. For SMS devices, the default display name is the phone number. The following restrictions apply to display_name (maximum length: 100 characters): Can be a string with spaces and with category L letters, numbers ([0-9]), or the characters - + / . ( ).

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
order
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_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
            "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_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
            "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_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
    "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.

FIDO2/WebAuthn

Endpoints related to the FIDO2/WebAuthn configuration for this particular Futurae Service. In particular, for Services that wish to make use of FIDO authentication with WebAuthn, they will behave as WebAuthn Relying Parties (or RP for short), and will have an associated WebAuthn RP Configuration resource.

Get RP Configuration

Example request:

GET /srv/admin/v1/webauthn/rp_config

GET /srv/admin/v1/webauthn/rp_config

Get the existing WebAuthn RP Configuration for this Service.

Response 200

Example response:

200 OK
{
    "rp_origin": "https://your.login.domain.example.com",
    "rp_id": "example.com",
    "rp_display_name": "Example Application",
    "attestation_preference": "none",
    "authenticator_selection": {
        "require_resident_key": false,
        "user_verification": "required"
    }
}

The request was successful. The corresponding WebAuthn RP Configuration record is returned.

Response 404

Example response:

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

The RP configuration for this Service does not exist (it has not been created yet, or it has been deleted). Call Create RP Configuration to create it.

Create RP Configuration

POST /srv/admin/v1/webauthn/rp_config

Create the WebAuthn RP Configuration for this Service. Each Service has at most one RP Configuration associated with it, so trying to invoke multiple times this endpoint on the same Service will fail.

Body Parameters

Example request body params:

{
    "rp_origin": "https://your.login.domain.example.com",
    "rp_id": "example.com",
    "rp_display_name": "Example Application",
    "attestation_preference": "none",
    "authenticator_selection": {
        "require_resident_key": false,
        "user_verification": "required"
    }
}
rp_origin
string
required
The Relying Party origin as defined in the WebAuthn RP Configuration resource.
rp_id
string
required
The Relying Party identifier as defined in the WebAuthn RP Configuration resource.
rp_display_name
string
required
Α display name for the Relying Party as defined in the WebAuthn RP Configuration resource.
attestation_preference
string
optional
Τhe Relying Party's default Attestation Conveyance Preference. Refer to the WebAuthn RP Configuration resource for details.
authenticator_selection
object
optional
Τhe Relying Party's default Authenticator Selection Criteria. Refer to the WebAuthn RP Configuration resource for details.

Response 200

Example response:

200 OK

Request was successful. The WebAuthn RP Configuration for this Service was successfully created.

Response 400

Example response:

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

Invalid or missing parameters or the WebAuthn RP Configuration already exists for this Service.

Modify RP Configuration

PUT /srv/admin/v1/webauthn/rp_config

Modify the existing WebAuthn RP Configuration for this Service, by supplying the attributes to be updated.

Body Parameters

Example request body params:

{
    "rp_origin": "https://changed.login.domain.example.com",
    "authenticator_selection": {
        "user_verification": "required"
    }
}
rp_origin
string
optional
The Relying Party origin as defined in the WebAuthn RP Configuration resource.
rp_id
string
optional
The Relying Party identifier as defined in the WebAuthn RP Configuration resource.
rp_display_name
string
optional
Α display name for the Relying Party as defined in the WebAuthn RP Configuration resource.
attestation_preference
string
optional
Τhe Relying Party's default Attestation Conveyance Preference. Refer to the WebAuthn RP Configuration resource for details.
authenticator_selection
object
optional
Τhe Relying Party's default Authenticator Selection Criteria. Refer to the WebAuthn RP Configuration resource for details.

Response 200

Example response:

200 OK
{
    "rp_origin": "https://changed.login.domain.example.com",
    "authenticator_selection": {
        "user_verification": "required"
    }
}

Request was successful. Depending on the supplied request body parameters the response body will contain the values of all the WebAuthn RP Configuration attributes that were 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 RP configuration for this Service does not exist (it has not been created yet, or it has been deleted). Call Create RP Configuration to create it.

Delete RP Configuration

Example request:

DELETE /srv/admin/v1/webauthn/rp_config

DELETE /srv/admin/v1/webauthn/rp_config

Delete the existing WebAuthn RP Configuration for this Service. You can then call Create RP Configuration to create a new one, if needed.

Response 200

Example response:

200 OK

The request was successful. The RP Configuration for this Service has been deleted.

Response 404

Example response:

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

The RP configuration for this Service does not exist (it has not been created yet, or it has been deleted). Call Create RP Configuration to create it.

Hardware Tokens

Endpoints related to the management of hardware tokens. The main resource that these endpoints target is the Hardware Token record.

Get List of Hardware Tokens

GET /srv/admin/v1/hwtokens

Query the list of hardware tokens that belong to the Futurae Organization to which this particular Futurae Service belongs, and are accessible by the latter. (A hardware token which is currently enrolled to users belonging to a different Service within the Organization remains accessible only by that particular service, until it is unenrolled from all assigned users. For more information refer to the Hardware Token resource.)

Use query parameters in order to specify search criteria, pagination and ordering. Unless specified differently, the hardware tokens returned are sorted by their serial_number attribute.

Query Parameters

Example request query params:

verbose=true&serial_number=GAQT00062000
status
string
optional
Search for the specified hardware token status strings, given as a comma-separated list. The available values are enrolled, unenrolled, archived. If omitted, all devices are returned.
serial_number
string
optional
Search for the specified serial number. The search is case insensitive and a partial match.
Minimum length: 3 characters.
verbose
boolean
optional
If set to true, the complete Hardware Token record is returned, otherwise the record will only contain the following fields: hwtoken_id, serial_number, enrolled_device_ids.
Default: false
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 records by a specific field.
Available fields: serial_number, created_at
Default: serial_number
order
string
optional
Choose between ascending (asc) and descending (desc) order for sorting the returned results.
Default: asc

Response 200

Example response:

200 OK
{
    "count": 1,
    "hwtokens": [
        {
            "created_at": 1592568445,
            "enrolled_device_ids": [
                "6caa3156-9014-417e-b369-6d0f5bfd62a4"
            ],
            "hwtoken_id": "41694d5c-465b-4244-955b-d34870f11072",
            "manufacturer": "GEMALTO",
            "model": "QR Code",
            "ocra_suite": "OCRA-1:HOTP-SHA256-6:QH64",
            "serial_number": "GAQT00062000",
            "token_type": "qr_code"
        }
    ],
    "limit": 25,
    "offset": 0,
    "total": 1
}

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.
hwtokens
[object]
The list of Hardware Token records, as a JSON array.

Response 400

Example response:

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

Invalid parameters.

Get Hardware Token Details

Example request:

GET /srv/admin/v1/hwtokens/d493e631-4ba7-4a47-84d5-fd9e14ebeb10

GET /srv/admin/v1/hwtokens/{hwtoken_id}

Get information about the hardware token with ID hwtoken_id.

Response 200

Example response:

200 OK
{
  "created_at": 1592568445,
  "enrolled_device_ids": [
      "6caa3156-9014-417e-b369-6d0f5bfd62a4"
  ],
  "hwtoken_id": "41694d5c-465b-4244-955b-d34870f11072",
  "manufacturer": "GEMALTO",
  "model": "QR Code",
  "ocra_suite": "OCRA-1:HOTP-SHA256-6:QH64",
  "serial_number": "GAQT00062000",
  "token_type": "qr_code"
}

The request was successful. The corresponding Hardware Token record is returned.

Response 403

Example response:

403 Forbidden
{
    "error": true,
    "code": 40300,
    "message": "forbidden"
}

The specified token cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization.

Response 404

Example response:

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

The specified hwtoken_id does not exist.

Archive a Hardware Token

Example request:

DELETE /srv/admin/v1/hwtokens/d493e631-4ba7-4a47-84d5-fd9e14ebeb10

DELETE /srv/admin/v1/hwtokens/{hwtoken_id}

This call archives an existing hardware token. Once archived, a hardware token is no longer available to use, for example you cannot assign it to a user anymore. This call sets the archived_at timestamp of the hardware token record to reflect the archiving time, and also automatically unenrolls it from any user that it is currently enrolled to.

This call is useful for decommissioning defective or end-of-life tokens (for example, a TOTP token whose battery has been depleted), as well as revoking tokens that have been reported as lost or stolen.

Response 200

Example response:

200 OK

The request was successful. The specified token has been archived.

Response 403

Example response:

403 Forbidden
{
    "error": true,
    "code": 40300,
    "message": "forbidden"
}

The specified token cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization.

Response 404

Example response:

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

The specified hwtoken_id does not exist.

Response 410

Example response:

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

The specified hwtoken_id has already been archived.

Resynchronize TOTP Token

Example request:

POST /srv/admin/v1/hwtokens/d493e631-4ba7-4a47-84d5-fd9e14ebeb10/resync

POST /srv/admin/v1/hwtokens/{hwtoken_id}/resync

This call is used in order to resynchronize the drift of a TOTP hardware token's internal clock with the Futurae backend. Small clock drifts (up to a few minutes) should be automatically adjusted under normal operation of the token, and in particular upon every successful user authentication with the token. During normal operation conditions, the Futurae backend is able to keep track of the token's ever changing clock drift and thus stay in sync.

Nevertheless, for tokens with very long periods of inactivity, or for tokens that have never been used for a long time after their production, it could be the case that the clock of the token drifts so much that the Futurae backend eventually becomes "desynchronized". Once this happens, subsequent authentication attempts will always fail. Use this call to provide two freshly generated, subsequent TOTP values of the token, so that the server can search for and synchronize with the tokens's current clock drift, using a sufficiently wide time window.

Two subsequent TOTP values are required for the resynchronization operation.

Body Parameters

Example request body params:

{
    "passcode1": "123123",
    "passcode2": "456456"
}
passcode1
string
required
The first of the two required sequential TOTP values produced by the token.
passcode2
string
required
The second of the two required sequential TOTP values produced by the token.

Response 200

Example response:

200 OK

Request was successful. The token's clock drift has been resynchronized with the Futurae backend successfully.

Response 400

Example response:

400 Bad Request
{
    "error": true,
    "code": 40000,
    "message": "failed to verify resync passcodes within specified window"
}

The specified hwtoken_id corresponds to a token of an invalid type (this call is only valid for TOTP hardware tokens), the required parameters are invalid or missing, or the supplied sequential TOTP values could not be found within the server's search window.

Response 403

Example response:

403 Forbidden
{
    "error": true,
    "code": 40300,
    "message": "forbidden"
}

The specified token cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization.

Response 404

Example response:

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

The specified hwtoken_id does not exist.

Response 410

Example response:

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

The specified hwtoken_id has already been archived.

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"
    ],
    "created_at": 1496154161,
    "failed_attempts": 0,
    "max_attempts": 15,
    "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
optional
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. A value of 15 (which is the default value) means that the user will be locked out on the 16th consecutive failed attempt. The default value can be configured per each Futurae Service in Futurae Admin (newly created users will have the specified default value).
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.
last_active_at
sting
optional
The date when this user was last active. Represented as a formatted string (e.g. "2019-05-23 00:00:00") of the last day that the user was active.
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).
fido Authentication using FIDO2/WebAuthn.
mobile_auth Single device authentication (aka mobile only), 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.
hwtoken_totp Generate time-based one-time codes using a hardware token 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).

Default allowed factors assignments

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": "approve",
    "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 three types of devices:

The Device resource is defined in the following table:

Example Device objects:

Mobile app device example:

{
    "capabilities": [
        "approve",
        "mobile_totp",
        "qr_code"
    ],
    "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
}

FIDO device example:

{
    "capabilities": [
        "fido"
    ],
    "created_at": 1608728971,
    "device_id": "d3085f1c-f8c6-4326-bf5d-b976229785f2",
    "display_name": "My security key",
    "enrolled": true,
    "enrolled_at": 1608728971,
    "type": "fido",
    "updated_at": 1608728971,
    "user_id": "5314f043-9397-49ce-9953-19a175f8fd9c"
}

Hardware token device example:

{
    "capabilities": [
        "hwtoken_totp"
    ],
    "created_at": 1594299386,
    "device_id": "d0b4746b-1f02-409d-892c-abae473244b7",
    "display_name": "GALT10530000",
    "enrolled": true,
    "enrolled_at": 1594299386,
    "hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10",
    "type": "hwtoken",
    "updated_at": 1594299386,
    "user_id": "40de80c1-68fe-42ba-b68e-2152940dbf31"
}

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 has the following values according to the type of device:
  • For a mobile app device, it's the device model.
  • For a FIDO device, the word fido.
  • For a hardware token, its serial number.
  • For an SMS device, the phone number.
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 to a user, 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
This field is not applicable for SMS devices. It can have the following values:
  • android for Android mobile devices.
  • ios for iOS mobile devices.
  • fido for FIDO devices.
  • hwtoken for hardware token devices.
hwtoken_id
string
optional
The ID of the corresponding Hardware Token record. This field is only applicable for hardware token devices.
version
string
optional
The currently installed Futurae mobile app version. This field is only applicable for 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 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.
migrated_from_device_id
string
optional
The ID of the device this device was migrated from. This field is only applicable for mobile app devices and will be present if this device was automatically enrolled during Automatic Account Recovery from a previous device.
migrated_to_device_id
string
optional
The ID of the device this device was migrated to. This field is only applicable for mobile app devices and will be present if this device was migrated to a new device during Automatic Account Recovery.
migrated_at
number
optional
The time, represented as a Unix timestamp, when this device was migrated to the device with ID migrated_to_device_id. This field is only applicable for mobile app devices and will be present if this device was migrated to a new device during Automatic Account Recovery.

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).
fido The device supports FIDO authentication.
mobile_totp The device can generate time-based one-time codes from within the Futurae mobile app.
hwtoken_totp The device is a hardware token that can generate time-based one-time codes.
qr_code The device supports authentication based on QR code scanning. This capability is available in the Futurae mobile app as well as hardware tokens with type qr_code.
sms The device can receive SMS one-time codes.

Hardware Token

This resource represents a physical hardware token device. Refer to this section for endpoints that can be used to managed them. There exist two types of hardware tokens:

Before presenting the Hardware Token resource attributes, we list a few important things that you should keep in mind when dealing with hardware in the Futurae APIs.

A Hardware Token resource represents a physical hardware token device and its device-specific properties. On the other hand, a Device resource represents a generic device that belongs to a specific user in the system, and its API specific properties.

A token can be either active or archived; archived tokens have been revoked and cannot be used again. An active token can be either enrolled to one or more users, or unenrolled. (If the token is indeed enrolled to multiple users, then all must belong to the same Service. The reason for this is explained further below.)

All the available hardware tokens that pre-exist in the system, are represented using the Hardware Token resource and belong to a specific Futurae Organization. The set of available hardware tokens for a particular Futurae Service consists of all the tokens in the Organization (to which the Service belongs) that have not been enrolled yet and all the tokens that have been already enrolled within the calling Service. In other words, unenrolled tokens are visible by all Services within a Futurae Organization, however, once a token is enrolled for a user, then the Service to which the user belongs reserves the token for its own use only. This implies that:

The Hardware Token resource is defined in the following table:

Example Hardware Token objects:

QR Code token example:

{
    "created_at": 1592568445,
    "enrolled_device_ids": [
        "6caa3156-9014-417e-b369-6d0f5bfd62a4"
    ],
    "hwtoken_id": "41694d5c-465b-4244-955b-d34870f11072",
    "manufacturer": "GEMALTO",
    "model": "QR Code",
    "ocra_suite": "OCRA-1:HOTP-SHA256-6:QH64",
    "serial_number": "GAQT00062000",
    "token_type": "qr_code"
}

TOTP token example:

{
    "created_at": 1592568433,
    "hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10",
    "manufacturer": "iana.GEMALTO",
    "model": "LAVA",
    "serial_number": "GALT10530000",
    "token_type": "totp"
}
Fields
hwtoken_id
string
A unique ID for the hardware token record.
serial_number
string
The Serial Number is a unique identifier defined by the manufacturer.
manufacturer
string
The name of the manufacturer.
model
string
The model name as provided by the manufacturer.
token_type
string
The type of the hardware token. Can be qr_code or totp (see further up for description of the two types).
activation_code
string
optional
Τhis code, if it exists, is required to activate the hardware token before the user can start using it. This field is only applicable for QR Code tokens which support this feature.
preset_pin
string
optional
The hardware token's pre-set PIN, if any. This field is only applicable for QR Code tokens which support this feature.
puk
string
optional
The hardware token's PIN unlock code. This can be used to unlock the token in case it has been blocked due to excessive wrong PIN attempts. This field is only applicable for QR Code tokens which have a PIN function.
ocra_suite
string
optional
The OCRA suite string definition used by the hardware token. This field is only applicable for QR Code tokens.
enrolled_device_ids
[string]
optional
The list of Device IDs enrolled with this hardware token. This field will only be returned for enrolled tokens.
created_at
number
The time when this hardware token record was created in the system, represented as a Unix timestamp.
archived_at
number
optional
The time when this hardware token was archived, represented as a Unix timestamp. If the token is active (enrolled or unenrolled), this field will not exist.

Enrollment

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

Example Enrollment object:

{
    "activation_code": "CQJUlLMhG8Ox807lJMec1nHj2nfoPVBVBcoJSbH0qjs=",
    "activation_qrcode_data_uri": "data:image/png;base64,iVBORw...(truncated)...Jggg==",
    "activation_qrcode_url": "https://futurae.com/qr?enroll=CQJUlLMhG8Ox807lJMec1nHj2nfoPVBVBcoJSbH0qjs=",
    "activation_code_short": "o2nf aoxi 1bxy wo71",
    "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 also serves as an ID for the Enrollment resource.
activation_qrcode_url
string
The URL for a PNG image of a scannable QR code that can be used to enroll a Futurae mobile app device.
activation_qrcode_data_uri
string
PNG image of a scannable QR code in data URI scheme. This is the same QR code image that can be retrieved via activation_qrcode_url.
activation_code_short
string
optional
A short activation code, suitable for manual user entry in the app, and is useful in case the user's phone has a malfunctioning camera or if the user does not want to give the app permission to access the camera.
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.

WebAuthn RP Configuration

This resource represents the WebAuthn Relying Party (RP for short) configuration parameters for a Futurae Service. When a Service has an RP configuration defined, it enables its users to register and use FIDO2/U2F authenticators for authentication using WebAuthn.

The WebAuthn RP Configuration resource is defined in the following table:

Example WebAuthn RP Configuration object:

{
    "rp_origin": "https://your.login.domain.example.com",
    "rp_id": "example.com",
    "rp_display_name": "Example Application",
    "attestation_preference": "none",
    "authenticator_selection": {
        "authenticator_attachment": "cross-platform",
        "require_resident_key": false,
        "user_verification": "required"
    }
}
Fields
rp_origin
string
The Relying Party origin. The origin's scheme must be https. The origin's port is unrestricted.
rp_id
string
The Relying Party identifier. This is a valid domain string that identifies the WebAuthn Relying Party. This value must be a registrable domain suffix of or is equal to the RP origin's effective domain. For example, given a Relying Party whose origin is https://login.example.com, then the following values are valid: login.example.com and example.com, but not m.login.example.com and not com.

For more information, refer to the WebAuthn specification.
rp_display_name
string
Α display name for the Relying Party. The rp_id, the respective Futurae Service name, or your application's name are all good examples for this value.
attestation_preference
string
Τhe Relying Party's default Attestation Conveyance Preference. It is one of the following values: none, direct, indirect, the default being none. This will be the value used by default when enrolling FIDO authenticators for users belonging to this Service, unless an override value is supplied when performing a specific enrollment. For an explanation of these values, refer to the WebAuthn specification.
authenticator_selection
object
optional
Τhe Relying Party's optional default Authenticator Selection Criteria, which will be used by default when enrolling FIDO authenticators for users belonging to this Service, unless an override value is supplied when performing a specific enrollment. This object consists of the following fields:

authenticator_attachment (string, optional): The FIDO authenticator's attachment modality. It can be either platform (such as Touch ID on Apple devices) or cross-platform (aka roaming authenticator, such as USB FIDO tokens). The default value is "", which means that both types of authenticators are accepted.

require_resident_key (boolean, optional): The Relying Party's requirements regarding resident credentials. The default value is false.:

user_verification (string, optional): The Relying Party's requirements regarding user verification. It can be required, preferred, or discouraged. The default value is preferred, however we strongly recommend to change it to discouraged or required, as explained below.












© Copyright 2024 Futurae Technologies AG.