Interacting with the UNLOQ API

Our current API version is v1 and the root URL is https://api-authenticator.iwelcome.com/v1. All non-https requests will be ignored and redirected to https. In some cases (eg. approval requests), the HTTP request might take up to 30 seconds because we initiate the approval request and wait for the user to provide some feedback. It is only after the user has provided the feedback that we generate the response and send it back to you. Therefore, it is highly recommended that you set your HTTP client's timeout to 40 seconds, so that it will not automatically close the connection before we fetch the user's feedback.

Whenever your application wants to interact with the UNLOQ API, it will do so on behalf of one of your UNLOQ applications. Our API will authorize the request by looking at the the HTTP headers we use for this purpose:

• Authorization - Bearer {your application API Key}
• Content-Type - application/json

All our API's responses will return JSON objects, with a type property that will tell youthe name of the action. When a successful response is generated, it will have the structure below, along with a 200 OK status code.

{
  "type": "api.application.reports.authorization",
  "meta": {
    "total_count": 19,
    "page_count": 2,
    "current_count": 9,
    "current_page": 2
  },
  "result": {} // this is either an object{} or an array[], depending on the expecting result.
}

Whenever an error is returned by the API, the response's status code will be 4xx or 5xx, depending on the gravity of the situation. 4xx means something is wrong on your end, while 5xx means something is wrong on our end. The error response JSON will always have the structure below.

{
  "error": {
    "code": "{full-caps error code}",
    "ns": "namespace of the error",
    "message": "user-friendly message describing the error",
    "status": "{error code like 4xx}"
  }
}

Pagination is also available for all API endpoints that return an array of objects. The following query parameters can be included for find operations:

• limit (integer, default 10, max 100) - The number of objects per page
• page (integer, default 1) - The current page of the result set
• start_date (timestamp) - If specified, objects will be filtered based on their created_at field.
• end_date (timestamp) - If specified, objects will be filtered based on their created_at field.
• order (enum, ASC or DESC, default DESC) - The sorting order of the result set.
• order_by (string, default created_at) - If specified, the sorting will be done based on the given field name

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.