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:
- Combine the api key and api secret, separating the two with a single colon (":").
- Encode that string using base 64.
- 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