Authentication

To interact with the CDS Global API, you must authenticate your requests using an access token.

The API uses the OAuth 2.0 client credentials flow to generate access tokens for server-to-server communication.

CAUTION

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

Before you begin

To get started, you’ll need the following credentials:

• Client ID
• Client Secret

If you don’t yet have credentials, contact your CDS account manager to request access.

Request an access token

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"
}

Make an authenticated request

You can now use the access token to make a request to your desired API endpoint, include the access token in the Authorization header when making API requests.

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'

Token lifecycle

• Access tokens are valid for 1 hour (expires_in: 3600)
• You should cache and reuse tokens until they expire
• When a token expires, request a new one using the same process

Scopes

Scopes define what your application is allowed to access within the API.

For example:

• order.read allows you to retrieve order data
• order.write allows you to create or update orders

Each set of client credentials is associated with one or more scopes. All API endpoints are restricted by scope, so your credentials must include the required scope to access 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.

Next steps

Now that you’re authenticated, you can:

• Explore available endpoints in the API Reference
• Start building your integration using the sandbox environment
• Configure webhooks to receive real-time updates (if applicable)