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