Application Authentication

Calls to the Jilia API are authenticated using OAUTH. All requests to Jilia must provide a valid token to be successful. The following sections describe the process for obtaining and using tokens.

Registered Application

After you register and are activated at docs.jilia.io, you have the ability to create a new developer application at your Apps page.

Your Apps page will update to include the new application. When expanded, the application displays, among other items, the Consumer Key and Consumer Secret values.

These two values are the crendentials required to obtain an authorization token.

NOTE: Do not share your application key and secret! For example, any publically accessible web application created using Jilia should not have, as part of the client loaded script, these values. This is especially true for the application secret. These values should be stored securely on your application server.

Token Request

The Jilia API exposes an OAUTH resource at: https://api.jilia.io/v1/oauth/accesstoken

An access token associated with your application is obtained by sending an HTTP POST request to the above URL. The request must contain two pieces of information:

  1. Grant type
  2. Application credentials

Grant Type

Regardless of the method selected to send the credentials, the request must specify the type of credentials provided as client_credentials. It is sent in the POST body as grant_type=client_credentials.

Application Credentials

There are two mechanism to provide application credentials in a token request:

  1. A base64 encoded value in the request header.
  2. As application/x-www-form-urlencoded parameters in the request body.

Both methods are valid and have the same result. It is up to you to decide what makes the most sense to use in your project. The first step of the Quick Start page provides an example using the request header. And the API documentation requests a token by passing the credentials in the request body.

Credentials in the Request Header

To construct the authorization header, base64 encode the string constructed as key:secret. That is the Consumer Key and Consumer Secret values provided as part of our registered appication, joined together using a colon.

Authorization: Basic base64(key:secret)

The mechanism for the base64 encoding is specific to your development language. The examples below are for JavaScript (in the browser) and node. Similar methods can be found for C#, Python, Ruby, and Go

JavaScript
// window.btoa('key:secret');
window.btoa('wKVFsG40bG4EosDt3NZpAnNMa4pAdA89:XdsHpDLMNKh1PMrf');
Node
// new Buffer('key:secret').toString('base64');
new Buffer('wKVFsG40bG4EosDt3NZpAnNMa4pAdA89:XdsHpDLMNKh1PMrf').toString('base64');

The result of encoding our key/secret pair is: d0tWRnNHNDBiRzRFb3NEdDNOWnBBbk5NYTRwQWRBODk6WGRzSHBETE1OS2gxUE1yZg==. This is the value we add to the header of our POST request.

Authorization: Basic d0tWRnNHNDBiRzRFb3NEdDNOWnBBbk5NYTRwQWRBODk6WGRzSHBETE1OS2gxUE1yZg==

cURL Request

With the crendentials and data ready to send, we can use any HTTP client to make the request for a token. The example below uses a cURL command. Note the -H argument to set the header, and the -d argument to provide the data.

curl -XPOST https://api.jilia.io/v1/oauth/accesstoken  -H "Authorization: Basic d0tWRnNHNDBiRzRFb3NEdDNOWnBBbk5NYTRwQWRBODk6WGRzSHBETE1OS2gxUE1yZg=="  -d "grant_type=client_credentials"

jQuery Request

The following example is a JavaScript function that accepts the key and secret values, performs the request using the jQuery ajax method, and returns a jQuery deferred object.

function requestToken(key, secret) {
  var credentials = btoa(key + ':' + secret);

  var requestConfig = {
    url: 'https://api.jilia.io/v1/oauth/accesstoken',
    type: 'post',
    data: {
      'grant_type': 'client_credentials'
    },
    beforeSend: function(request){
      request.setRequestHeader('Authorization', 'Basic ' + credentials);
    }
  };

  var jqxhr = jQuery.ajax(requestConfig);
  return jqxhr;
}

Credentials in the Request Body

The application key and secret pair are provided in the request body are passed as client_id and client_secret respectively.

The following cURL example requests a token for the application key wKVFsG40bG4EosDt3NZpAnNMa4pAdA89 and secret XdsHpDLMNKh1PMrf. Note the -d argument to provide the request body data.

curl -XPOST https://api.jilia.io/v1/oauth/accesstoken -d "grant_type=client_credentials&key=wKVFsG40bG4EosDt3NZpAnNMa4pAdA89&secret=XdsHpDLMNKh1PMrf"

Token Response

The Jilia API response to a token request is a JSON object. The most important property of the object is access_token. The value for access_token will be included in all requests to the Jilia API.

{
  "issued_at": "1444311332096",
  "scope": "",
  "application_name": "31f6470a-d277-4ab5-9b65-74cb1d2bcf5b",
  "status": "approved",
  "api_product_list": "[Jilia API]",
  "expires_in": "3599",
  "developer.email": "jilia-developer@jilia.io",
  "organization_id": "0",
  "token_type": "BearerToken",
  "client_id": "wKVFsG40bG4EosDt3NZpAnNMa4pAdA89",
  "access_token": "CY3DolwJAGoLwS3DJVVG0VGyXXYf",
  "organization_name": "centralite",
  "refresh_token_expires_in": "0",
  "refresh_count": "0"
}

Also note that the issued_at timestamp and expires_in seconds can be used to calculate when the token will expire. This can be useful in your application logic to preemptively request a new token when needed, as opposed to reacting to an unauthorized error response. Here is an example of such a response:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
WWW-Authenticate: Bearer realm="null",error='invalid_token",error_description='keymanagement.service.access_token_expired: Access Token expired"
Content-Length: 116
Connection: keep-alive{
  "fault": {
    "faultstring": "Access Token expired",
    "detail": {
      "errorcode": "keymanagement.service.access_token_expired"
    }
  }
}

Using the Token

The token is provided to Jilia either in the header of the HTTP request or as a query parameter appended to the URL.

cURL Request

The following cURL request is to the Jilia root location. The result will be a listing of available servers. Unlike the request to obtain a token, where the "Authorization" header (-H) specified a Basic value, we are now providing a Bearer token.

curl -XGET https://api.jilia.io/v1/  -H "Authorization: Bearer CY3DolwJAGoLwS3DJVVG0VGyXXYf"

The same GET request with the access token provided as a query parameter:

curl -XGET https://api.jilia.io/v1?access_token=CY3DolwJAGoLwS3DJVVG0VGyXXYf

jQuery Request

The following example is a JavaScript function that accepts a token, performs the request using the jQuery ajax method, and returns a jQuery deferred object.

function getServers(token) {

  var requestConfig = {
    url: 'https://api.jilia.io/v1/',
    type: 'get',
    beforeSend: function(request){
      request.setRequestHeader('Authorization', 'Bearer ' + token);
    }
  };

  var jqxhr = jQuery.ajax(requestConfig);
  return jqxhr;

}

And again using the query parameter instead of a header to provide the token.

function getServers(token) {

  var requestConfig = {
    url: 'https://api.jilia.io/v1?access_token=' + token,
    type: 'get'
  };

  var jqxhr = jQuery.ajax(requestConfig);
  return jqxhr;

}