API v3 – Authentication

The Retailer API uses the OAuth 2.0 standard with the grant-type ‘Client Credentials’. By using OAuth 2.0 we use a standardized, intuitive and broadly supported form of authentication to help you connect to our API.

See https://oauth.net/2/ for any additional information about the OAuth 2.0 standard.

The following steps will indicate how to use OAuth 2.0 with our Retailer API.

Please note that this flow is intended only for retailers developing their own connection. For intermediaries participating in the intermediary partner program, a different flow is available. Please visit the relevant partner platform page for more information.

 

Step 1 – The API client credentials

The first step in this process is gathering your API credentials, which can be found in your seller dashboard. We will use fake public and private keys in the examples on this page.

Warning: Do not use the following keys in your own code, these are fake codes and only used in this example.

Client_id: oRNWbHFXtAECmhnZmEndcjLIaSKbRMVE
Client_secret: aQHPOnmYkPZNgeRziPnQyyOJYytUbcFBVJBvbMKoDdpPqaZbaOiLUTWzPAkpPsZFZbJHrcoltdgpZolyNcgvvBaKcmkqFjucFzXhDONTsPAtHHyccQlLUZpkOuywMiOycDWcCySFsgpDiyGnCWCZJkNTtVdPxbSUTWVIFQiUxaPDYDXRQAVVTbSVZArAZkaLDLOoOvPzxSdhnkkJWzlQDkqsXNKfAIgAldrmyfROSyCGMCfvzdQdUQEaYZTPEoA

 

Step 2 – Requesting Bearer token

Use the API keys to request a valid Authentication token from the OAuth server: https://login.bol.com/token.

There are 2 ways to request the bearer token:

  • Basic Auth header
  • HTTP POST body

 

Basic Auth Header

When using an HTTP client, it is possible to set a Basic Auth header. See https://hc.apache.org/httpcomponents-client-ga/tutorial/html/authentication.html for additional information for the Apache HTTP client.

The HTTP client will use the Authorization header:

Authorization: Basic encoded_client_id encoded_client_secret

Perform a POST request with the following structure:

Method: POST
Host: https://login.bol.com/token?grant_type=client_credentials
Accept: application/json

— HTTP client will take care of this —

Authorization: Basic encoded_client_id encoded_client_secret

Note: No POST body is required.
Note: Only Accept: application/json is supported by the OAuth server.

 

HTTP POST Body

To use this endpoint perform a POST request with the following structure:

Method: POST
Host: https://login.bol.com/token
Content-Type: application/x-www-form-urlencoded
Accept: application/json

Body: client_id=oRNWbHFXtAECmhnZmEndcjLIaSKbRMVE&client_secret= MaQHPOnmYkPZNgeRziPnQyyOJYytUbcFBVJBvbMKoDdpPqaZbaOiLUTWzPAkpPsZFZbJHrcoltdgpZolyNcgvvBaKcmkqFjucFzXhDONTsPAtHHyccQlLUZpkOuywMiOycDWcCySFsgpDiyGnCWCZJkNTtVdPxbSUTWVIFQiUxaPDYDXRQAVVTbSVZArAZkaLDLOoOvPzxSdhnkkJWzlQDkqsXNKfAIgAldrmyfROSyCGMCfvzdQdUQEaYZTPEoA&grant_type=client_credentials

Note: Only Accept: application/json is supported by the OAuth server.

 

The endpoint will have a response that looks like this:

{
"access_token":" utTJFMrOKwlyB5rcBpCIP6Dtn0k4w8vtqR6TJtu-fvEIm9tXTZf6q4JSaRaxRc7eSgO4EAggELN5bqADCSGq4mDEQgM-k-VPUi7IVIkKrVAFdwyb9Yz1cXy9 BspU96tZSmxjNiNzMiLCJvcmciOiJTTFI6MTMyMjAzNiIsImF6cCI6IjMwODE4NWVhLTkyZTAtNGE0NS1iNzg2LWU5MzI1OTIyM2I3MyIsImNsaWVudG5hbWUiOiJDaGFubmFWFmYyRdvKZyB4PibGUiLCJpc3MiOiJsb2dpbi5ib2wuY29tIiwic2NvcGVzIjoiQ3VzdG9tU2NvcGU0IEN1c3RvbVNjb3BlMyIsImV4cCI6MTUzOTI0NDkwMSwiaWF0IjoxNTM5MjQ0NjAxLCJhaWQiOiJTTFI6MTMyMjAzNiIsImp0aSI6IjI1YzcxZDY2LTU0YzgtNDQ3ZS04NTk0LWEwMzFlZDNkNGUzOSJ9.Nkc90mTB-BLVJEnSDHx2o1bkJ-eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIzMDgxODVlYS05MmUwLTRhNDUtYjc4Ni1lOTMyNTkyM7Dan9VaFQF1o8EvlGCV42n61KAjeEg8PrjVwqFvJ8y9QUzcpTFXQ5f4VFgIfZfYaqZyM2iJWFlpSpVl-jQAiGjOp0xSForKtGe2-FdyXmmQNpw_IltcPmvJIGABU3Xngx5O- _F13sG_zRoy7g1CBspU9dx5DLDuOa17PBmj52kQVEV8Q",
"token_type": "Bearer",
"expires_in": 299,
"scope": "{scopes}"
}

In the response message, it is clarified that the token_type is “Bearer”. This means that the ‘Authorization’ header will be of the following structure:

Bearer access_token

Example:

Bearer utTJFMrOKwlyB5rcBpCIP6Dtn0k4w8vtqR6TJtu-fvEIm9tXTZf6q4JSaRaxRc7eSgO4EAggELN5bqADCSGq4mDEQgM-k-VPUi7IVIkKrVAFdwyb9Yz1cXy9 BspU96tZSmxjNiNzMiLCJvcmciOiJTTFI6MTMyMjAzNiIsImF6cCI6IjMwODE4NWVhLTkyZTAtNGE0NS1iNzg2LWU5MzI1OTIyM2I3MyIsImNsaWVudG5hbWUiOiJDaGFubmFWFmYyRdvKZyB4PibGUiLCJpc3MiOiJsb2dpbi5ib2wuY29tIiwic2NvcGVzIjoiQ3VzdG9tU2NvcGU0IEN1c3RvbVNjb3BlMyIsImV4cCI6MTUzOTI0NDkwMSwiaWF0IjoxNTM5MjQ0NjAxLCJhaWQiOiJTTFI6MTMyMjAzNiIsImp0aSI6IjI1YzcxZDY2LTU0YzgtNDQ3ZS04NTk0LWEwMzFlZDNkNGUzOSJ9.Nkc90mTB-BLVJEnSDHx2o1bkJ-eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIzMDgxODVlYS05MmUwLTRhNDUtYjc4Ni1lOTMyNTkyM7Dan9VaFQF1o8EvlGCV42n61KAjeEg8PrjVwqFvJ8y9QUzcpTFXQ5f4VFgIfZfYaqZyM2iJWFlpSpVl-jQAiGjOp0xSForKtGe2-FdyXmmQNpw_IltcPmvJIGABU3Xngx5O- _F13sG_zRoy7g1CBspU9dx5DLDuOa17PBmj52kQVEV8Q

Note: The response from the OAuth server indicates when the access_token will expire: “expires_in”: {time_in_seconds}. After this timeframe in seconds, a new Bearer token has to be requested. The client_id and client_secret remain the same.

 

Step 3 – Use bearer token in API request

When using any request on the API, send the Authorization header with the Bearer token.

Example:

Method: GET
Host: https://api.bol.com/retailer/orders
Accept: application/json
Authorization: Bearer utTJFMrOKwlyB5rcBpCIP6Dtn0k4w8vtqR6TJtu-fvEIm9tXTZf6q4JSaRaxRc7eSgO4EAggELN5bqADCSGq4mDEQgM-k-VPUi7IVIkKrVAFdwyb9Yz1cXy9 BspU96tZSmxjNiNzMiLCJvcmciOiJTTFI6MTMyMjAzNiIsImF6cCI6IjMwODE4NWVhLTkyZTAtNGE0NS1iNzg2LWU5MzI1OTIyM2I3MyIsImNsaWVudG5hbWUiOiJDaGFubmFWFmYyRdvKZyB4PibGUiLCJpc3MiOiJsb2dpbi5ib2wuY29tIiwic2NvcGVzIjoiQ3VzdG9tU2NvcGU0IEN1c3RvbVNjb3BlMyIsImV4cCI6MTUzOTI0NDkwMSwiaWF0IjoxNTM5MjQ0NjAxLCJhaWQiOiJTTFI6MTMyMjAzNiIsImp0aSI6IjI1YzcxZDY2LTU0YzgtNDQ3ZS04NTk0LWEwMzFlZDNkNGUzOSJ9.Nkc90mTB-BLVJEnSDHx2o1bkJ-eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIzMDgxODVlYS05MmUwLTRhNDUtYjc4Ni1lOTMyNTkyM7Dan9VaFQF1o8EvlGCV42n61KAjeEg8PrjVwqFvJ8y9QUzcpTFXQ5f4VFgIfZfYaqZyM2iJWFlpSpVl-jQAiGjOp0xSForKtGe2-FdyXmmQNpw_IltcPmvJIGABU3Xngx5O- _F13sG_zRoy7g1CBspU9dx5DLDuOa17PBmj52kQVEV8Q