API Reference

Learn how to access UNLOQ end points

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.unloq.io/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.unloq.io/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.