Authentication

Every request to the XOi External API must include a valid access token. This token ensures that requests originate from a trusted integration partner. A unique api key and api secret are issued to each partner and can be used to retrieve an access token. Tokens remain valid for 60 minutes.

API URLs

• Testing: https://api-users-external.staging.xoeye.com/stag/token
• Production: https://api-users-external.xoi.io/prod/token

Including an Access Token on API requests

All requests to the XOi External API must include a valid Access Token. This token should be passed in via the Authorization header for each request. No prefix is required -- the token itself should be included as the full content of the Authorization header.

See the individual API docs for examples.

Retrieving an Access Token

Authentication is performed by making a REST request to one of the API URLs listed above.

Access tokens are valid for 60 minutes, after which they will be rejected by the API. Requesting a new access token does not invalidate previously requested tokens.

JSON POST Request

The API key and secret can be submitted via a JSON request which is POSTed to one of the endpoints listed at the top of this guide.

Here is an example of the JSON to be submitted:

{
  "api_key": "api key supplied by XOi",
  "api_secret": "api secret supplied by XOi"
}

Here is an example cURL request to retrieve an access token using that JSON (saved in a file named credentials.json for the purposes of this example):

curl -X POST -d "@credentials.json" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  https://api-users-external.staging.xoi.io/stag/token

Upon successful authentication, the token will be returned as JSON in a format similar to this:

{ "token": "eyJraW..." }

Basic Authenticated GET Request

Alternatively, a token can be retrieved via a GET request which passes the API key and secret using basic authentication. The api key and secret should be supplied as the username and password, respectively.

Here is an example cURL request to retrieve an access token:

USERNAME="api key supplied by XOi"
PASSWORD="api secret supplied by XOi"

curl -X GET --user "$USERNAME:$PASSWORD" \
  -H "Accept: application/json" \
  https://api-users-external.staging.xoeye.com/stag/token

Upon successful authentication, the token will be returned as JSON in a format similar to this:

{ "token": "eyJraW..." }

Manually crafting an Authorization header for basic authentication

In the absence of a helper to create an appropriate basic authentication header, the process is relatively simple:

1. Combine the api key and api secret, separating the two with a single colon (":").
2. Encode that string using base 64.
3. Prepend the resulting sequence of characters with the word "Basic" and set the "Authorization" header for the request to the token endpoint to the resulting string.

This process, if written in some generic pseudocode, looks a bit like this:

api_key = "api key supplied by XOi"
api_secret = "api secret supplied by XOi"

combined_secrets = "{api_key}:{api_secret}"
encoded_secrets = encode_as_base64(combined_secrets)

headers["Authorization"] = "Basic {encoded_secrets}"

The resulting header would be: Basic YXBpIGtleSBzdXBwbGllZCBieSBYT2k6YXBpIHNlY3JldCBzdXBwbGllZCBieSBYT2kK