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_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.
||Use the username provided to you. The signature is further discussed below.|
||Alphanumeric||This is one of the numerous commands listed on the main page.|
||Alphanumeric||This can be any number or alphanumeric string (e.g. hexadecimals), but must be unique per each API call.|
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
The following pieces of information/data are needed to compute the signature.
|secret||String||This is the password provided to you, which acts as the key for the hashing algorithm.|
||Currently, this will always be
|command||Alphanumeric||This is the exact same value provided in the
|nonce||Alphanumeric||This is the exact same value provided in the
|payload||String||This is the HTTP request body, i.e., the raw
All following examples will be using PHP as a means to illustrate any coding requirements.
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;
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);
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);
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.