Authentication

Before you can use the Affiliate Reporting API you need to take a few steps to gain access. For any and all authorized endpoints we require partners to authenticate themselves. On this page we will describe the steps you need to take to make sure your application can authenticate against the Affiliate Reporting API.

Technology

Before covering the details of authenticating with bol, here’s a list describing the technologies used. Well-known standards are used to allow seamless integration with tools and frameworks used by our customers.

OAuth2

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, and living room devices. This allows applications to easily interact with OAUTH2 compliant services, as the specification has been widely adopted in programming languages, tools and frameworks.

Using OAUTH2 users can authenticate and request an access token, which will be in JWT format.

Please visit the OAuth 2.0 website for detailed documentation on OAUTH2 specification.

Detailed information on the different parts of the OAuth2 specifications are mapped here.

JSON Web Tokens

The access tokens used by the Affiliate Reporting API are JSON Web Tokens (JWT). These tokens will provide clients access to Affiliate Reporting API endpoints for a limited time and are used to determine the identity of the caller.

JWT tokens are signed by the OAUTH2 service and verified by the Affiliate Reporting API on every call, to make sure the integrity of the caller is still guaranteed.

Encoded inside the tokens is some basic information describing the client. This data can be introspected to troubleshoot issues, but it is not possible to modify the contents of the token as the signature will no longer match and requests using this token will be rejected. JWT is a standard that is supported by many different languages, frameworks and tools.

For more details on JSON webtokens and usage scenarios, please review the documentation on the JWT website.

In addition, tools for introspecting tokens are available online, such as the JWT debugger.

Client Credentials Flow

The client credentials flow is the flow that can commonly be used in service to service authentication. Partners can use a set of specifically created credentials to use in their applications.

The three steps below will guide you through the process of getting credentials and performing actual requests with the Affiliate Reporting API.

Step 1: Acquiring API credentials

Any partner willing to interact with the Affiliate Reporting API will need a set of credentials (Client ID and a Client Secret), which can be acquired through the Seller Dashboard (SDD).

After having successfully signed up up for the Affiliate Program, perform the following steps:

Log in to the bol.com Affiliate Program.
Navigate to the section where it’s possible to acquire the API credentials.

First, click Account:

Secondly, scroll down to the Open API section:
Create API credentials.

Click the Toevoegen button to start adding a Credential, the following popup will be shown:

Enter a meaningful name to be able to distinguish the various credentials if you have more than one.

After creating it, the just created credential will be shown in the list of credentials.

Obtain Client ID and Client Secret

The Client ID can be obtained by copying the shown value, or clicking the copy-to-clipboard button on the right.

The Client Secret can be obtained by clicking Toon secret on which the secret will be shown in a popup.

Copy both Client ID and Client Secret and go to step 2.

Show Secret

You should never share your Client IDs and Client Secrets with others or even with bol. This information should also not be hardcoded into the codebase since it will show up in source control. Failure to comply with this rule could result in your credentials being revoked without notice. You can create new credentials at any time, but the revoked credentials will become inaccessible.

Step 2: Acquiring an access token

Next up is acquiring a token from our authentication service and to set this as an authorization header when doing calls to the Affiliate Reporting API. In order to get the token send a POST request to https://login.bol.com/token?grant_type=client_credentials with your Client Id and Client Secret. For performing previous operation you can use tools like Postman.

Set up headers

In order to request a token from login.bol.com, start by creating the authorization header, for basic authentication. The authorization header is set up in the following way:

Authorization: Basic <credentials>

The credentials part is the concatenation of the Client ID, a colon (:) and the Client Secret, which are then base64 encoded.

Some tools (like Postman) encode the header value themselves so you don’t need to do it.

<Client ID>:<Client Secret>

Please note that at this time the authentication service only supports Accept: application/json, so providing different values may lead to unexpected errors.

Most programming languages and HTTP libraries will support Basic auth (and OAuth2 for that matter). The process described here is the manual approach, but we encourage the utilization of libraries to handle this for you.

Requesting the token

After setting the headers, request a token by doing a POST with no body to the following URI:

https://login.bol.com/token?grant_type=client_credentials by doing the following request: curl --location --request POST 'https://login.bol.com/token?grant_type=client_credentials' \ --header 'Accept: application/json' \ --header 'Authorization: Basic <encodedBase64(clientId:secret)>'

The endpoint will respond with a 200 OK response when credentials are provided properly. You will receive the following response body:

{
    "access_token": "<access_token>",
    "token_type": "Bearer",
    "expires_in": 299,
    "scope": "<scopes>"
}

The token type returned is indeed a Bearer token, the value in the access_token field contains the token that should be used in interaction with the Affiliate Reporting API. Extract this value and proceed to step 3.

If the credentials have not been correctly provided, you will receive a 401 Unauthorized response from the server.

For those familiar with curl, this is an example command:

curl -X POST 'https://login.bol.com/token?grant_type=client_credentials' \
  --user '$clientId:$clientSecret'

As mentioned before, the JWT token returned here in the access_token field can be introspected. Tokens have a limited validity, the duration of which is embedded in the token. You can use a JWT compatible library to extract the expiration value from the token, so you will know exactly when it is time to retrieve a new token. You can also check the other information in the token in order to identify the affiliate account the token is linked to, which can be useful for applications that deal with several affiliate accounts.

Please do not request a new token for each request to the Affiliate Reporting API! The tokens are valid for longer periods of time and are intended to be reused. Not doing so can overload the authentication and will lead to an IP ban when request limits are exceeded. Note that the rate limits for the authentication service are far lower than those of the Affiliate Reporting API

Step 3: Setting the authorization headers

The last step to take is passing the token that was just acquired as an authentication header when requesting data from the API. The structure for setting up the authorization header is as follows:

Authorization: Bearer <token>

There’s no encoding involved, just concatenate the word Bearer <token> (including the space!) and the token together. Next, set the other API specific headers, such as the Accept-Language header before doing the request, depending on the targeted endpoint. Now you can call the Affiliate Reporting API endpoints.

If the API returns an error message with status code 401 Unauthorized or 403 Forbidden, please check if you successfully applied the steps, check the token validity and the status of your affiliate account to see why this is happening.

Under normal circumstances you should receive a response in the 2xx range, telling you your request has been successfully processed.

The Bearer token is required on all authenticated endpoints for the Affiliate Reporting API. The process is the same, regardless of the endpoint being called.

An example (curl) request would look like the following:

curl 'https://api.bol.com/marketing/affiliate/reports/v2/order-report?startDate=2019-10-30&endDate=2024-12-31' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $token'