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
Headers:
   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}"
  }
}
      

Notes

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';
request.post({
    url: 'https://api-authenticator.iwelcome.com/v1/authenticate',
    headers: {
      'Authorization': 'Bearer ' + apiKey
    },
    form: {
      email: 'john@doe.com',
      ip: '1.1.1.1',
      method: "UNLOQ"
    }
  }).then(function(resp) {
    var token = resp.result.token;
    console.log(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.
          break;
        case 'APPROVAL.TOKEN':
          // Use has previously denied a request and he needs to provide the OTP
          break;
        case 'APPROVAL.TIMEOUT':
          // User has failed to approve or deny the request, or his device was unreachable.
          break;
        default:
          // A different error has occurred.
      }
    } catch(e) {
      // Something went really wrong.
      console.error(e);
    }
  });
      

Notes

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.