Making authenticated requests

Unless explicitly documented all XPKit API requests require an Authorization HTTP header containing an OAuth 2.0 bearer token. Tokens can be requested from the Auth API.

If you are unfamiliar with OAuth 2.0 and the authorization flows it provides, it may be helpful to read about these first. OAuth 2.0 Simplified is a good resource.

Auth API

XPKit's Auth API can be found at the following addresses:

Region	Service URL
AMER	auth.amer.xpkit.net
APAC	auth.apac.xpkit.net
China	auth.china.xpkit.cn
EMEA	auth.emea.xpkit.net

Please speak to your XPKit account administrator to determine which region you should use.

Each application you build will be assigned an OAuth 2.0 client ID and secret with appropriate scopes (see the Authentication section for full details). These credentials should be exchanged for an access token and this should be used in the Authorization header.

Requesting a new access token

Assume your application has been assigned the following credentials:

Region	Client ID	Client Secret
EMEA	ExSY8d5iam299El4s2DHpWJxNVJCG0	ON3LhyQu66Us305EcPG38CaCgQVpBL1IgxJlyaEtiA4KgN2xX59N

You would request a token like so:

Endpoint     https://auth.emea.xpkit.net/api/token/
HTTP method  POST
Parameters   grant_type=client_credentials
             client_id=ExSY8d5iam299El4s2DHpWJxNVJCG0
             client_secret=ON3LhyQu66Us305EcPG38CaCgQVpBL1IgxJlyaEtiA4KgN2xX59N

Examples

cURL

curl -v -L -X POST \
    -d 'grant_type=client_credentials&client_id=ExSY8d5iam299El4s2DHpWJxNVJCG0&client_secret=ON3LhyQu66Us305EcPG38CaCgQVpBL1IgxJlyaEtiA4KgN2xX59N' \
    https://auth.emea.xpkit.net/api/token/

Python

import requests

payload = {
    'grant_type': 'client_credentials',
    'client_id': 'ExSY8d5iam299El4s2DHpWJxNVJCG0',
    'client_secret': 'ON3LhyQu66Us305EcPG38CaCgQVpBL1IgxJlyaEtiA4KgN2xX59N'}
req = requests.post(
    url='https://auth.emea.xpkit.net/api/token/',
    data=payload)
result = req.json()

If everything worked correctly you will receive back a status code of 200 and a JSON payload:

{
    "token_type": "Bearer",
    "scope": "profiles:read activities:read",
    "expires_in": 36000,
    "access_token": "TQvIUQZiaixrKamgQWooCuZXl8COoc"
}

Note: the scope field contains all the permissions the application has been granted. In this example the application has been granted read access to both the profile and activity resources. See a list of all the available resources here. If a required access level for a particular resource is missing, an account administrator can configure the granted scopes in XPKit Portal.

If there was a problem with the request the JSON response will contain error and extra_info details along with an appropriate status code:

{
    "error": "Unauthorized",
    "extra_info": {"error": "invalid_client"}
}

Making authenticated requests to XPKit

Take the access token from the response above and add a HTTP Authorization header to any subsequent XPKit requests like so:

Authorization: Bearer TQvIUQZiaixrKamgQWooCuZXl8COoc

Token management

The token will expire in 36000 seconds (10 hours after it was granted). It is suggested the application saves this token and uses it for all requests within this time period. Once the token has expired, if it is used again the status code received from any XPKit endpoint will be 403 (forbidden).

When the token has expired the application should request a new one.