UNLOQ API Reference

POST /enroll

Initiates the second-factor user enrollment process, returning a QR-image URL the user can then scan with their mobile app. Once a user is enrolled, your application will then be able to send authentication approvals to their device.

POST https://api-authenticator.iwelcome.com/v1/enroll
Headers:
   Authorization: Bearer {your application API Key}
   Content-Type: application/json

Body parameters

email (string, required) - The user's e-mail address.
name (string, optional) - The profile display name that will appear in the application. If it is not provided, your application name will be used instead.

Result format (200 OK)

{
   "type": "api.application.enroll.user",
   "result": {
    "exists": false,
    "qr_url": "https://widget-authenticator.iwelcome.com/qr/....",
    "expire_at": "2017-04-24T05:15:32.698Z"
  }
}

Error format (4xx)

{
   "error": {
    "code": "{e.code}",
    "ns": "{e.ns}",
    "message": "{e.message}",
    "status": "{e.statusCode}"
  }
}

Notes

E-mail profiles that are enrolled using this method and do not previously exist are called virtual profiles. A virtual profile can only be used to authenticate on the application that initiated the enrollment process. Therefore, you can also provide e-mails such as: {uuid}@{yourdomain}.com. Since we do not validate these e-mail addresses, we will not send e-mails towards them.

A virtual profile can also be enrolled by multiple applications, however it would appear under the same name in the user's mobile app. A short example is detailed below.

Example flow

- Application A calls POST /v1/enroll with e-mail: 339642f8-8d84-454a@domaina.com and a QR image is generated.
- The user downloads the UNLOQ mobile app and scans the QR image provided by Application A. This concludes the user on-boarding experience.
- Application A calls POST /v1/authenticate with the above e-mail address.
- User receives an approval push notification to their device.
- Application B calls POST /v1/enroll with the same e-mail address. Another QR image is generated.
- The user uses the mobile app's Add profile functionality and scans the QR image. Their device is now linked with application B.
- Application B can now perform POST /v1/authenticate requests.
- Application C tries to perform POST /v1/authenticate with the above e-mail. The request fails since the user was not previously enrolled with application C.

Implementation suggestion

- In your your application's profile page, call GET /v1/enrolled with the user's e-mail address
- If the API call returns enrolled=true, the user is already enrolled. You can display the Two-step enabled message
- If the API call returns enrolled=false, perform a POST /v1/enroll with the user's e-mail address and a display name. The API call will return a QR image.
- Display the QR image (in SVG format) in your application and ask the user to download the app and scan the QR image.

Have a question? You can always send us an email at support@unloq.io, or contact us on chat.

For security related concerns, please visit our Security page.

API Reference