API Service Documentation

Advanced Authentication

For the purposes of this page, "alphanumeric" refers to a string of characters that are numbers and/or letters from the ASCII table, including underscores.
If a string extends beyond the mentioned set of characters, it will be referred to as a general "string."

The purpose of Advanced Authentication is to provide an extra layer of security. It is done by no longer requiring the submission of the password in its original form within the request. It is replaced with a digest, or signature, that utilizes the password as a key for encryption. Since the server has your passowrd, it will be able to recompute the signature by doing a simple look-up on your username and verify that the request came from you. With the introduction of a nonce, a request also cannot be resubmitted more than once and must use a new nonce and thus requires recomputation of the signature.

When using this authentication method, you will no longer be required to provide the ai_login_id, ai_login_password, or ai_command in the POST body. Although you may, it is not recommended. If you do, it must be considered part of the "payload" when computing the signature.

Required Headers

Header	Format	Notes
`Authorization`	`AI {username}:{signature}`	Use the username provided to you. The signature is further discussed below.
`X-AI-Command`	Alphanumeric	This is one of the numerous commands listed on the main page.
`X-AI-Nonce`	Alphanumeric	This can be any number or alphanumeric string (e.g. hexadecimals), but must be unique per each API call.

Example HTTP Request

POST /service
Host: www.example.com
Authorization: AI johnsmith:GAczUet9UL0oUbZPRSf+ssph/xtxqJrr/NSXvI/1z6o=
X-AI-Command: ping
X-AI-Nonce: 5e0c6da0
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Content-Length: 21

foo=ABC012&bar=xyz789

Computing the Signature

The following pieces of information/data are needed to compute the signature.

Data	Format	Notes
secret	String	This is the password provided to you, which acts as the key for the hashing algorithm.
method	`POST \| GET \| PUT \| DELETE`	Currently, this will always be `POST`. When we start to provide fully RESTful API calls, it will support the four typical HTTP methods.
command	Alphanumeric	This is the exact same value provided in the `X-AI-Command` header.
nonce	Alphanumeric	This is the exact same value provided in the `X-AI-Nonce` header.
payload	String	This is the HTTP request body, i.e., the raw `POST` body. Currently, all requests are `POST`, so this should rarely be empty. When we start to provide fully RESTful API calls, `GET` and `DELETE` methods will expect this to be a present, but empty string.

All following examples will be using PHP as a means to illustrate any coding requirements.

Step 1: Construct the Message

The message is constructed by concatenating the method, command, nonce, and payload together, in that exact order, separated by a NULL character between them.

$message = $method . "\0" . $command . "\0" . $nonce . "\0" . $payload;

Step 2: Calculate the Signature

The signature is calculated by running the message through an HMAC hashing function, using the secret as they key and using 'SHA256' as the hashing algorithm. Depending on your programming/scripting language, make sure to capture the signature in a raw binary format (e.g. not in hexadecimal encoding). The only exception would be if your function returns or can return in base64 encoding, which is Step 3.

$signature = hash_hmac('sha256', $message, $secret, true);

Step 3: Preparing the Signature for Transport

Once you have the signature calculated, it should be encoded in base64 before it is placed in the Authorization header. If the HMAC function in the previous step encoded this for you, you can skip to Step 4.

$signature_encoded = base64_encode($signature);

Step 4: Construct the `Authorization` Header

When your signature is finally encoded, simply concatenate your API username and signature together, using a colon (:) as a delimiter. Don't forget to prefix the authorization type of AI in your header, leaving a space before the username-signature string.

header('Authorization: AI ' . $username . ':' . $signature_encoded);

You will now be able to authorize your API call without exposing your password in its original form in the payload. You can use the very first example above, which uses a password of abcXYZ123 if you need to verify your program/script for accuracy.