Authentication

xChange uses the OAuth 2.0 client credentials flow for authenticating requests.

Please get in touch with your CDS account manager to get your client credentials.

CAUTION

Client credentials are highly sensitive information, you must ensure that these are kept safe and secret.

You can use the following request to get an access token for sandbox environment.

CURL

curl -X POST https://sandbox.cdsglobal.co.uk/v1/oauth2/token \
	 -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET"

If your request is succesful, you'll receive a JSON response as following:

JSON

{
    "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IkM5Q0JBNDhFNDlFOUJDMDc0RTUzNzJEMTM3NzM1OUMwNTNDQkRDMzkiLCJ4NXQiOiJ5Y3VramtucHZBZE9VM0xSTjNOWndGUEwzRGsiLCJ0eXAiOiJhdCt...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "order.read"
}

TIP

The access token is valid for one hour, therefore this can be cached to avoid unnecessary requests to the token endpoint.

You can now use the access token to make a request to your desired API endpoint.

The following example illustrates a typical API request.

CURL

curl -X GET https://sandbox.cdsglobal.co.uk/v1/orders?email=john.doe@cdsglobal.co.uk \
	--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
	--header 'Content: application/json'

Scopes

Access can be limited to certain entities and actions using scopes. If required, multiple sets of client credentials with different scopes can be provided for an environment. This allows for third parties to integrate with xChange without having to give access to all endpoints. For example, a third party might require information about a customer, but they shouldn't be allowed to change any of that information.

Each set of client credentials have a list of allowed scopes that is returned as part of the authentication request. All endpoints are scope-restricted, therefore you need to use an appropriate set of client credentials to receive the required access for an endpoint.

Available scopes

Scope	Access granted
customer.read	All GET requests to customer entity.
customer.write	All POST and PUT requests to customer entity. (ie Update Customer)
entitlement.read	All GET requests to entitlement entity.
offer.read	All GET requests to offer entity.
order.read	All GET requests to order entity.
order.write	All POST and PUT requests to order entity. (ie Pause Subscription)

Please check the API Reference for the required scope for each endpoint.