UNLOQ API Reference

POST /authorize/:code

Initiates an authorisation request and sends it to the specified user's device. For the authorisation request to work, the user must have previously authenticated in the application.

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

URL parameters

code (string, required) - The authorisation action code to use. This will be used as a template.

Body parameters

unloq_id (integer, required) - The UnloqID of the target user. The user must have previously authenticated to the requested application.
email (email) - Default is null. Only used when unloq_id not available.
reference (string, required) - An authorisation reference that will be displayed on the user's device. This can be viewed as an external id, with a maximum length of 20 characters.
ip (IP) - The originating IP address that will be displayed on the user's device.
{variables} - Any number of variable names, defined in the authorisation action.
generate_token (boolean) - Optional. Default is false

Result format (200 OK)

{
  "type": "api.application.approval.authorize",
  "result": {
    "unloq_id": "1234",
    "token": "abcdefgh12345"
  }
}

Error format

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

Node.js example code

// The following code will initiate an authorisation request, using the following action
// representation:
//    code: 'transfer'
//    title: 'Transfer resource $name?'
//    message: 'Are you sure you want to transfer $name to the user $target?'
var request = require('request');
var apiKey = 'YOUR-API-KEY';
request.post({
    url: 'https://api-authenticator.iwelcome.com/v1/authorize/transfer',
    headers: {
      'Authorization': 'Bearer ' + apiKey
    },
    form: {
      unloq_id: 1,
      reference: 'abcdefg12',
      name: 'Server 1',
      target: 'john@doe.com'
    }
  });
// The resulting authorisation request will display the following messages:
// - title: 'Transfer resource Server 1?'
// - message: 'Are you sure you want to transfer Server 1 to the user john@doe.com?'

Notes

Authorisation requests work with previously defined authorisation actions. When initiating an authorisation request, next to the required body parameters (unloq_id, reference), you may send additional variable names, defined in the authorisation action.

As an example, if an action's message would contain the variables $amount and $company, you will then be able to perform this POST request with amount=10 and company=My company, while the provided values 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.

API Reference