Enrollment

This section describes how to enroll users and their devices in Futurae using the Auth API.

Enrollment with the Futurae Mobile App

Before being able to use authentication for a user of your application, you must first enroll the user and his mobile device on the Futurae server. Each user can have multiple enrolled devices, but he must have at least one enrolled device in order to be able to use authentication. For most authentication factors, such as Approve, the Futurae mobile app (or your app which has the Futurae SDK integrated) has to be installed on the user’s device and paired with that user’s account.

The following flowchart illustrates the basic steps for performing an enrollment:

In summary:

1. Instruct the user to install the Futurae mobile app (or your mobile app which has the Futurae SDK integrated) on his device, in case he does not already have the application installed.

2. Call /user/enroll (in particular either Enroll a New User or Enroll a New Device for an Existing User) and display to the user the activation QR code. The QR code can be retrieved and displayed using two alternatives:

   1. Through the activation_qrcode_data_uri response key which contains the PNG image of the QR code inlined in data URI format. This is the recommended way.

   2. If for some reason you cannot make use of the data URI option, you can alternatively use the URL contained in the activation_qrcode_url response key to retrieve the PNG image of the QR code.

   The user uses the camera of his device in order to scan the QR via the Futurae app.

   Alternatively, if the user is performing the enrollment process from the mobile device on which he installed the app, he can tap on the link provided by the activation_code_uri response key, which will automatically invoke the Futurae mobile app. In both cases, and if the user’s device has internet connectivity, the device will be enrolled and associated with the particular user.

3. If you supplied a success_callback_url in /user/enroll you will automatically be notified via the callback once the enrollment completes successfully. Alternatively, you can poll the progress of the enrollment with the /user/enroll_status endpoint.

Enrollment with a Phone Number

In order to use SMS passcodes as an authentication factor, a user first needs to enroll the phone number of his device. In this case the enrollment process is slightly different, as it does not involve the Futurae mobile app:

1. Call /user/enroll (in particular either Enroll a New User with Phone Number or Enroll a New Phone Number for an Existing User) and supply the phone_number parameter.

2. Use the device_id contained in the response (which is associated with the above supplied phone number) to send a verification SMS code to the registered phone number using /user/sms_activation. In order to verify the code supplied by the user, the same endpoint can be used (refer to the API doc for details on the format of the request). If the code is correct then the particular phone number is considered enrolled with this user and can be used for sending SMS passcodes (“sms” factor in /user/auth).