API Reference

Learn how to access UNLOQ end points

POST /authenticate

Initiates an authentication request for the given e-mail. This is a Server-to-Server implementation of the UNLOQ authentication flow.

POST https://api-authenticator.iwelcome.com/v1/authenticate
   Authorization: Bearer {your application API Key}
   Content-Type: application/json
Body parameters
  • email (string, required) - The UNLOQ User e-mail that initiated the authentication process
  • unloq_id (string) - Optional. The UNLOQ id of the user when email is not available. Default is null.
  • method (enum) - Initiates the authentication request with the specified method. Values are: UNLOQ, EMAIL, OTP
  • ip (IP) - The originating IP address that will be displayed on the user's device.
  • token (integer) - Optional, the OTP token the user has provided. This is required for subsequent authentication requests, after a user has denied the request.
  • generate_token (boolean) - Optional. Default is true. When set to false, we return the information directly. Only works for UNLOQ/OTP.
  • ask_trusted (boolean) - Optional. Default is false.
  • source_client (object) - Optional. Default is null.
  • public_key (string) - Optional. Default is null.
  • {variables} - Optional. Any number of variable names.
Result format (200 OK)
   "type": "api.application.approval.authenticate",
   "result": {
    "unloq_id": "1234",
    "token": "abcdefgh12345"
Error format (4xx)
   "error": {
    "code": "{e.code}",
    "ns": "{e.ns}",
    "message": "{e.message}",
    "status": "{e.statusCode}"

Unlike the UNLOQ browser widget, the calling server is not required to provide the 2FA token at the initial authentication request, because it is considered a safe source. However, in order to prevent spam requests to the user's device, once the user has denied an authentication request, the token field of the API call will become mandatory and the error APPROVAL.TOKEN will start occurring.

Node.js example code
var request = require('request');
var apiKey = 'YOUR-API-KEY',
    apiSecret = 'YOUR-API-SECRET';
    url: 'https://api-authenticator.iwelcome.com/v1/authenticate',
    headers: {
      'Authorization': 'Bearer ' + apiKey
    form: {
      email: 'john@doe.com',
      ip: '',
      method: "UNLOQ"
  }).then(function(resp) {
    var token = resp.result.token;
  }).catch(function(err) {
    try {
      var data = JSON.parse(err);
      switch(error.code) {
        case 'APPROVAL.DENIED':
          // user has denied the authentication request. We will need to provide the two factor token on the next request.
        case 'APPROVAL.TOKEN':
          // Use has previously denied a request and he needs to provide the OTP
        case 'APPROVAL.TIMEOUT':
          // User has failed to approve or deny the request, or his device was unreachable.
          // A different error has occurred.
    } catch(e) {
      // Something went really wrong.

When initiating an authentication request, next to the required body parameters, you may send additional variable names.

As an example, if an action's message would contain the variable $name, you will then be able to perform this POST request with name='Joe', while the provided value will replace the variable name in the message.

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.