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

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.

• username (maximum length: 100 characters): Can be a string with no spaces and with case-sensitive letters ([a-zA-Z]), numbers, or the characters . _ - = @ # $ +

• display_name (maximum length: 100 characters): Can be a string with spaces and with case-sensitive Unicode letters (Unicode L character class), Unicode punctuation (Unicode P character class), numbers, or the characters = @ # $ +

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

• The HTTP username will be your Service ID.
• The HTTP password will be a hex-formatted HMAC-SHA256 signature, computed over the request content in the way described below, using the Admin API key as the HMAC key.
• The HTTP username and password are concatenated using a colon, and the concatenated string is Base64 encoded.

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:

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

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

Copy{
    "time": "1461694259294"
}

Request was successful.

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

Copy{
    "api_version": "1.0.0"
}

Request was successful.

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

Copy{
    "time": "1461694259294"
}

Request was successful.

Response 401

Example response:

401 Unauthorized

Copy{
  "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:

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

Copy{
    "time": "1461694259294"
}

Request was successful.

Response 401

Example response:

401 Unauthorized

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

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

Update Service Information

Update Service information.

PUT /srv/admin/v1/info

Body Parameters

Example request body params:

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

Response 200

Example response:

200 OK

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

Request was successful.

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

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

Invalid parameters, for example accounts_migration_callback_url is not a string.

Get Stored Logo

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

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

Request was successful.

Response 404

Example response:

404 Not Found

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

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

Upload New 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:

Copy{
    "logo": "iVBORw0KGgoAAAANSU...(truncated)...bJP/DxeklQAAAABJRU5ErkJggg=="
}

Response 200

Example response:

200 OK

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

Request was successful.

Response 400

Example response:

400 Bad Request

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

Missing or invalid parameters.

Delete Stored Logo

DELETE /srv/admin/v1/logo

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

Response 200

Example response:

200 OK

Copy{
    "result": "ok"
}

Request was successful. The stored logo was removed.

Response 404

Example response:

404 Not Found

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

Response 200

Example response:

200 OK

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

Response 400

Example response:

400 Bad Request

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

Response 200

Example response:

200 OK

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

Response 400

Example response:

400 Bad Request

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

Response 200

Example response:

200 OK

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

Response 400

Example response:

400 Bad Request

Copy{
    "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:

Copy{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "valid_secs": 3600,
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity",
    "enrollment_flow_binding_enabled": false,
    "account_recovery_flow_binding_enabled": false
}

Response 200

Example response:

200 OK

Copy{
  "activation_code": "MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
  "activation_code_uri": "futurae://enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_universal_link": "https://futurae.com/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.

Response 400

Example response:

400 Bad Request

Copy{
  "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:

• Implicit: Pass the activation code to WebAuthnJS SDK's enroll() method in the background. The user will be able to activate his FIDO authenticator, being completely unaware of the activation code. This approach assumes that the enrollment process is sufficiently authenticated and/or attacker-free.
• Explicit: Get a short version of the activation code by supplying the short_code input param as true. Deliver the short activation code to the user using an out-of-band channel. When the user is about to activate his FIDO device, ask the user to supply the code and pass the supplied value to WebAuthnJS SDK's enroll() method. This approach increases the security of the FIDO registration step, and is useful when the activation process is not sufficiently authenticated or the risk that the attacker might be able to hijack the activation process is not acceptable.

Body Parameters

Example request body params:

Copy{
    "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",
    "enrollment_flow_binding_enabled": false,
    "account_recovery_flow_binding_enabled": false
}

Response 200

Example response:

200 OK

Copy{
    "activation_code": "NUhiSXk4eF9LRVE3SXdFZDZvRmVUeFd4Qy1BWGtPUlJZX1JnM0ctZm1EQWk6N2E3ZjUyMDktZWUwOS00ZDU0LThlYzAtY2Y2MTAyYjVmNGI2OmFwaS10ZXN0LmZ1dHVyYWUuY29t",
    "activation_code_short": "vr50 7gia qpsi qg8e",
    "enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
    "expiration": 1461694259,
    "user_id": "7a7f5209-ee09-4d54-8ec0-cf6102b5f4b6",
    "username": "someuser@domain.com"
}

Request was successful.

Response 400

Example response:

400 Bad Request

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

Copy{
    "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:

Copy{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10"
}

Response 200

Example response:

200 OK

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

Request was successful.

Response 400

Example response:

400 Bad Request

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

Example response (TOTP verification failed):

400 Bad Request

Copy{
  "error": true,
  "code": 40050,
  "message": "bad request"
}

Request failed. One of the following reasons apply:

• Invalid or missing parameters.
• A user with the specified username already exists.
• The specified hwtoken_id does not exist or has been archived.
• The specified hwtoken_id cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization. In this case, the code field within the JSON response will have the value 40051.
• The supplied hwtoken_passcode verification failed against the specified hwtoken_id. In this case, the code field within the JSON response will have the value 40050.

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:

Copy{
    "username": "someuser@domain.com",
    "display_name": "Some User",
    "phone_number": "+41123456789"
}

Response 200

Example response:

200 OK

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

Request was successful.

Response 400

Example response:

400 Bad Request

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

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

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

Copy{
    "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:

Copy{
    "allowed_factors": ["mobile_totp", "approve", "passcode"],
    "status": "enabled",
    "username": "newusername@domain.com",
    "display_name": "Cooler display name",
    "max_attempts": 15
}

Response 200

Example response:

200 OK

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

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

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

Invalid parameters, or the specified username already exists.

Response 404

Example response:

404 Not Found

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

The specified user id does not exist.

Response 410

Example response:

410 Gone

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

Copy{
    "result": "ok"
}

Request was successful. The specified user was deactivated.

Response 404

Example response:

404 Not Found

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

The specified user id does not exist.

Response 410

Example response:

410 Gone

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

Response 200

Example response:

200 OK

Copy{
    "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,
            "account_recovery_flow_binding_enabled": false,
            "device_integrity": "rooted",
            "device_integrity_updated_at": 1715851709
        }
    ]
}

Request was successful.

Response 404

Example response:

404 Not Found

Copy{
    "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:

Copy{
    "valid_secs": 3600,
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity",
    "account_recovery_flow_binding_enabled": true
}

Response 200

Example response:

200 OK

Copy{
  "activation_code": "MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_code_uri": "futurae://enroll?activation_code=MGg4R2pMQ3VjMUNHcFBNOE9tcXJ2Y3NVNnpkNmMwcDN5ZjJyaHhDODBuMDo1NThkZmYyOS0zZjhkLTRkNmYtYTY5Ni0wYWY3ODZlNmEzYjc6dGVzdHNydi5mdXR1cmFlLmNvbToxOTA4MA",
  "activation_universal_link": "https://futurae.com/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",
  "enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
  "expiration": 1461694259,
  "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
  "username": "someuser@domain.com"
}

Request was successful.

Response 400

Example response:

400 Bad Request

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

Invalid or missing parameters.

Response 404

Example response:

404 Not Found

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

The specified user id does not exist.

Response 410

Example response:

410 Gone

Copy{
    "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:

• Implicit: Pass the activation code to WebAuthnJS SDK's enroll() method in the background. The user will be able to activate his FIDO authenticator, being completely unaware of the activation code. This approach assumes that the enrollment process is sufficiently authenticated and/or attacker-free.
• Explicit: Get a short version of the activation code by supplying the short_code input param as true. Deliver the short activation code to the user using an out-of-band channel. When the user is about to activate his FIDO device, ask the user to supply the code and pass the supplied value to WebAuthnJS SDK's enroll() method. This approach increases the security of the FIDO registration step, and is useful when the activation process is not sufficiently authenticated or the risk that the attacker might be able to hijack the activation process is not acceptable.

Body Parameters

Example request body params:

Copy{
    "fido": true,
    "valid_secs": 3600,
    "authenticator_selection": {
        "user_verification": "required"
    },
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity"
}

Response 200

Example response:

200 OK

Copy{
    "activation_code": "NUhiSXk4eF9LRVE3SXdFZDZvRmVUeFd4Qy1BWGtPUlJZX1JnM0ctZm1EQWk6N2E3ZjUyMDktZWUwOS00ZDU0LThlYzAtY2Y2MTAyYjVmNGI2OmFwaS10ZXN0LmZ1dHVyYWUuY29t",
    "activation_code_short": "vr50 7gia qpsi qg8e",
    "enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
    "expiration": 1461694259,
    "user_id": "7a7f5209-ee09-4d54-8ec0-cf6102b5f4b6",
    "username": "someuser@domain.com"
}

Request was successful.

Response 400

Example response:

400 Bad Request

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

Invalid or missing parameters.

Response 403

Example response:

403 Forbidden

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

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

The specified user id does not exist.

Response 410

Example response:

410 Gone

Copy{
    "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:

Copy{
    "hwtoken_id": "d493e631-4ba7-4a47-84d5-fd9e14ebeb10"
}

Response 200

Example response:

200 OK

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

Request was successful.

Response 400

Example response:

400 Bad Request

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

Example response (TOTP verification failed):

400 Bad Request

Copy{
  "error": true,
  "code": 40050,
  "message": "bad request"
}

Request failed. One of the following reasons apply:

• Invalid or missing parameters.
• A user with the specified username already exists.
• The specified hwtoken_id does not exist or has been archived.
• The specified hwtoken_id cannot be accessed by this Futurae Service, as it is currently enrolled to users belonging to a different Service within the Organization. In this case, the code field within the JSON response will have the value 40051.
• The supplied hwtoken_passcode verification failed against the specified hwtoken_id. In this case, the code field within the JSON response will have the value 40050.

Response 404

Example response:

404 Not Found

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

The specified user id does not exist.

Response 410

Example response:

410 Gone

Copy{
    "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:

Copy{
    "phone_number": "+41123456789"
}

Response 200

Example response:

200 OK

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

Request was successful.

Response 400

Example response:

400 Bad Request

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

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

The specified user id does not exist.

Response 410

Example response:

410 Gone

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

The specified user has already been archived.

Response 403

Example response:

403 Forbidden

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

Copy{
    "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",
            "enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002"
        },
        {
            "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",
            "enrollment_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6"
        }
    ]
}

Request was successful.

Response 404

Example response:

404 Not Found

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

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

Response 404

Example response:

404 Not Found

Copy{
    "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:

Copy{
    "length": 8,
    "reuse_count": 1
}

Response 200

Example response:

200 OK

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

Response 400

Example response:

400 Bad Request

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

Invalid parameters.

Response 404

Example response:

404 Not Found

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

The specified user id does not exist.

Response 410

Example response:

410 Gone

Copy{
    "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:

Copy{
    "valid_secs": 60
}

Response 200

Example response:

200 OK

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

Request was successful.

Response 400

Example response:

400 Bad Request

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

Invalid parameters.

Response 404

Example response:

404 Not Found

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

The specified user id does not exist.

Response 410

Example response:

410 Gone

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

Response 200

Example response:

200 OK

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

Response 400

Example response:

400 Bad Request

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

Invalid parameters.

Response 404

Example response:

404 Not Found

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

Response 200

Example response:

200 OK

Copy{
    "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,
            "account_recovery_flow_binding_enabled": true,
            "device_integrity": "rooted",
            "device_integrity_updated_at": 1715851709
        }
    ],
    "limit": 25,
    "offset": 0,
    "total": 1
}

The request was successful.

Response 400

Example response:

400 Bad Request

Copy{
    "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:

Copy{
    "user_id": "7adc0abe-4820-4ba8-b8ea-a3eaa2860eb6",
    "valid_secs": 3600,
    "success_callback_url": "https://www.domain.com/enrollcallback?token=alongrandomstringforextrasecurity",
    "account_recovery_flow_binding_enabled": false
}

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

Copy{
    "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,
    "account_recovery_flow_binding_enabled": false,
    "device_integrity": "rooted",
    "device_integrity_updated_at": 1715851709
}

The request was successful. The corresponding Device record is returned

Response 404

Example response:

404 Not Found

Copy{
    "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:

Copy{
    "display_name": "My iphone",
    "account_recovery_flow_binding_enabled": false
}

Response 200

Example response:

200 OK

Copy{
    "display_name": "My iphone",
    "account_recovery_flow_binding_enabled": false
}

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.

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

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

Invalid parameters.

Response 404

Example response:

404 Not Found

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

The specified device id does not exist.

Response 410

Example response:

410 Gone

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

Copy{
    "result": "success"
}

Request was successful.

Response 404

Example response:

404 Not Found

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

The specified device id does not exist.

Response 410

Example response:

410 Gone

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

Response 200

Example response:

200 OK

Copy{
    "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",
            "enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
            "enrollment_flow_binding_enabled": false,
            "account_recovery_flow_binding_enabled": false
        },
        {
            "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",
            "enrollment_id": "cdde7d64-78ae-11ee-b962-0242ac120002",
            "enrollment_flow_binding_enabled": false,
            "account_recovery_flow_binding_enabled": false
        },
    ],
    "limit": 25,
    "offset": 0,
    "total": 2
}