API requests are authenticated with an API key pair. This key pair is made up of a Key ID and a Secret Key.

You can use your API key pair to authenticate requests in one of the following ways:

HTTP Header Authentication

To use HTTP Header authentication, just add the following headers to all requests:

    XIO-API-Key-ID: key-id
    XIO-API-Secret-Key: secret-key

Request Signature Authentication

Signature authentication is an alternative to header authentication when you want to send requests through an un-trusted 3rd party (for example, a users browser).

We'll use the following request to demonstrate request signature creation:

POST /v1/streams HTTP/1.1
Accept: */*
Connection: close
Content-Type: application/x-www-form-urlencoded
Host: api.x.io

application=10a0fb0c527f4acab9abd454975488fa&version=4713fa30b76b4932a3a5c145618228d1&file_provider_url=https%3A%2F%2Fexample.com%2Ffile_provider.json%3Fauth_key%3Dabcde123

To produce a signature, start by determining the HTTP method and URL of the request. These two are known when creating the request, so they are easy to obtain.

HTTP Method: POST

The base URL is the URL to which the request is directed, minus any query string or hash parameters. It is important to use the correct protocol here, so make sure that the "https://" or "http://" portion of the URL matches the actual request sent to the API. You should always be using "https://" with the X.IO API.

Base URL: https://api.x.io/v1/streams

Next, gather all of the parameters included in the request. There are two such locations for these additional parameters - the URL (as part of the querystring) and the request body. You will need to add the following parameters to the request:

AttributeDescription
expiresunix timestamp the request expires
key_idthe key id of your API key pair

In the HTTP request the parameters are URL encoded, but you should collect the raw values. These values need to be encoded into a single string which will be used later on. The process to build the string is very specific:

  1. Sort the list of parameters alphabetically by key.
  2. For each key/value pair:
    1. Append the key to the output string.
    2. Append the '=' character to the output string.
    3. Append the value to the output string.
  3. If there are more key/value pairs remaining, append a '&' character to the output string.

The following string will be produced by repeating these steps with the parameters collected above:

Parameter string: application=10a0fb0c527f4acab9abd454975488fa&expires=1401589102&file_provider_url=https://example.com/file_provider.json?auth_key=abcde123&key_id=LSBE0QDMLZOU7JPCZACBI4BWXE&version=4713fa30b76b4932a3a5c145618228d1

The three values collected so far must be joined to make a single string, from which the signature will be generated. This is called the signature base string.

To encode the HTTP method, base URL, and parameter string into a single string:

  1. Convert the HTTP Method to uppercase and set the output string equal to this value.
  2. Append the '&' character to the output string.
  3. Percent encode the URL and append it to the output string.
  4. Append the '&' character to the output string.
  5. Percent encode the parameter string and append it to the output string.

This will produce the following:

Signature base string: POST&https%3A%2F%2Fapi.x.io%2Fv1%2Fstreams&application%3D10a0fb0c527f4acab9abd454975488fa%26expires%3D1401589102%26file_provider_url%3Dhttps%3A%2F%2Fexample.com%2Ffile_provider.json%3Fauth_key%3Dabcde123%26key_id%3DLSBE0QDMLZOU7JPCZACBI4BWXE%26version%3D4713fa30b76b4932a3a5c145618228d1

The signature base string should contain exactly 2 ampersand '&' characters. The percent '%' characters in the parameter string should be encoded as %26 in the signature base string.

Finally, the signature is calculated by passing the signature base string and API secret key to the HMAC-SHA256 hashing algorithm.

The output of the HMAC signing function is a binary string. This needs to be URL-safe base64 encoded to produce the signature string. For example, the output given the base string and signing key given on this page is A1 BB 97 55 E5 4D F0 8C 21 75 4E 60 25 66 63 9E 90 3D 7E 5E AD 64 F8 DE C7 9F DE F9 3C 53 F6 C3. That value, when converted to URL-safe base64, is the signature for this request:

Signature: obuXVeVN8IwhdU5gJWZjnpA9fl6tZPjex5_e-TxT9sM

Once you have the final signature value, add a parameter to your request called signature with the calculated signature value.

URL-Safe Base64 Encoding

When passing binary data to the X.IO API, it must be base64 encoded using the following algorithm:

  1. Base64 encode data to create output string.
  2. From output string, replace all '+' with '-' and all '/' with '_'.
  3. Strip any '=' from the output string.

A simple Ruby method that performs the above function looks like this:

def safe_b64_encode(msg)
  Base64.strict_encode64(msg).tr("+/", "-_").gsub('=', '')
end