Authentication

Before you can use the Retailer 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 retailer API.

Technology

Before covering the details of authenticating with bol.com, 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 retailer API are JSON Web Tokens (JWT).These tokens will provide clients access to retailer 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 retailer 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’s 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.

JWT tokens for the OpenAPI

You can also use the Retailer API token for the OpenAPI. This means you do not need to provide an API key as a query parameter.

An example call would be: curl --request GET \ --url https://api.bol.com/catalog/v5/products/<product-id>; \ --header 'authorization: Bearer [jwt]. See Step 3: Setting the Authorization headers to learn how to set the Bearer token.

If you have previously been using an API key in your request, you can remove it from your system once you have your JWT token. Once you have done this please let us know which API keys you are no longer using so that we can remove them from our side.

Rate limits for the OpenAPI

If you migrate to using JWT tokens for OpenAPI authentication, your rate limits will change to become the limits used in the Retailer API. The OpenAPI calls will now have a limit of 5 requests per second, or effectively 18,000 an hour - although you will need to spread them out over that time. For more information, refer to Rate limits.

Authentication Flows

There are two primary authentication flows partners can use when interacting with the API. To know which one applies to you it is vital that you understand how you are going to connect to the API.

How you are using the API Type of authentication to use

You are not connecting to the API directly but are using an external service provider to interact with bol.com that is listed as a integration partner

Code Flow

You are not connecting to the API directly but are using an external service provider to interact with bol.com that is NOT listed as a bol.com partner

Client Credentials

You are connecting to the API directly, through software developed by yourself or a third party that directly interacts with the retailer API

Client Credentials

Code Flow

Targeted specifically to trusted integration partners of bol.com who expose our services to third party clients, the Code Flow authentication method will allow users to quickly grant access to their data to an external integrator. There are a few steps involved:

  • Go to the website of the integrator. They will have an option available to set up a connection with bol.com;

  • You will be redirected to the https://login.bol.com website, and are prompted to log in unsing the credentials for your retailer account;

  • After logging in, you will be presented with the option to allow access to the integrator;

  • After doing this, you will be redirected back to the integrator website, who can then retrieve a set of credentials to interact with the retailer API on your behalf;

  • For a full description of this process, see Intermediary authorization.

If, after granting access, you want to revoke access to the integration partner you can do so by removing the auhtorization from the Seller DashBoard application.

Unlisted integration partners

The code flow authentication is not available for unlisted and untrusted integration partners, unlisted partners can be provided with access to the API by creating client credentials specific to this integration partner.

If you are providing integration with the bol.com retailer API as a service and are currently unlisted, please fill in this form to get in touch with bol.com about becoming a listed partner.

Technical details on how to support the code flow integration with bol.com from your platform will be provided once you are accepted into the program.

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. This section of the documentation is specifically intended for:

  • Partners who want to connect their own software to the retailer API;

  • Integration partners who are not listed.

Step 1: Acquiring API credentials

Any partner willing to interact with the retailer API will need a set of credentials (a clientId and a clientSecret), which can be acquired through the Seller Dashboard (SDD).

Log in to SDD

Log in to SDD, open the settings page and find the section called 'API Instellingen'.

Creating client credentials in SDD

Provide technical contact details

Next, fill in the details of the technical contact. We need partners to supply this value so bol.com Partnerservice can get in touch whenever we see behavior on the API that should be optimized or prevented. Not supplying contact information will mean partners cannot access the API.

Please provide accurate information and update this if it may change in the future. Not having the correct information may result in an API ban if we are unable to reach the technical contact to discuss any unexpected behavior on the API.

More information on this topic is available in the API definition of services and usage.

Create API credentials

Next, credentials need to be created in the settings. After saving the technical contact information, new sections will be available to create credentials. Press the 'Aanmaken' button to open a dialog in which you can specify a specific name for the credentials.

Creating client credentials in SDD

In the textfield, provide a name for the credentials. This value is used to identify the credentials server side when doing requests and for retailers to identify what the keys are used for.

Creating client credentials in SDD

When deciding on a name for the credentials, please consider the use case for the credentials:

  • Credentials for an internal software system: Use the name of the software system;

  • Credentials for an external software system (such as an unlisted external integrator): Use the name of the integrator.

When done, press the blue button to create the credentials. They newly created credentials should now show up in the list.

To get the full set of credentials, click the 'Toon secret' link below the listed Client ID. A popup will open containing the ClientSecret.

Creating client credentials in SDD

These are the values you need to access the retailer API. In the next step, we will discuss how to use the credentials to gain access.

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 retailer API.

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 ClientId, a colon (:) and the ClientSecret, which are then base64 encoded.

<clientId>:<clientSecret>

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

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 retailer 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.

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 retailer account the token is linked to, which can be useful for applications that deal with several retailer accounts.

Please do not request a new token for each request to the retailer API! The tokens are valid for longer periods of time and are intended to be reused. Not doing so can overload the authentication service 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 retailer 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 (required) Accept header and optionally the Content-Type header before doing the request, depending on the targeted endpoint. Now you can call the retailer API (for instance the orders resource):

https://api.bol.com/retailer/orders

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 retailer account to see why this is happening (sometimes retailer accounts are blocked or blacklisted).

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 retailer API. The process is the same, regardless of the endpoint being called.

Please note that if you want to test the authentication flow, you can call one of our demo.adoc, as they will require the same authentication method and can be used to verify your implementation. You can also interact with production directly, depending on your preference.

Managing Access

Whenever you want to (re)create new credentials for different applications or manage who has access to your data, you can manage the credentials in your retailer account. There are two specific sections:

  • Client Credentials: This section contains the credentials that were manually created by your organization;

  • Authorized parties: This section contains credentials provided to listed integration partners.

You can revoke any access from either applications or parties that have access by pressing the trashcan icon behind the credentials. After being removed the credentials will stop working and parties will lose access. If you want to restore access, new credentials have to be created using the steps listed in this document.

Creating client credentials in SDD

Create separate credentials for separate purposes. Do not reuse the same credentials for your own app(s) to grant access to anyone else. If you need to revoke the credentials your own application will also lose access for shared credentials. It will also be more difficult for you and if you need to revoke the credentials your own application will also lose access for shared credentials. It will also be more difficult for you and bol.com to troubleshoot issues, as it is harder to differentiate which application might have integration issues if several of them are using the same credentials.
You should never share your clientIDs and clientSecrets with others or even with bol.com. 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.

More information

To help partners implement authentication and authorization properly with the retailer API we have also created a video which highlights a best practice for dealing with tokens: