Intermediary authorization on behalf of partners

Intermediaries who participate in bol.com’s Intermediary Partner Program can offer partners the opportunity to log in by entering their bol.com account details. This route makes it easier for partners to connect their own systems to bol.com and removes the need for the partner to request and enter API keys. It also provides bol.com with the ability to recognize which partners are connected through an intermediary to develop specific functionality for this target group.

Requirements

This flow is only available for intermediaries who participate in the bol.com Intermediary Partner Program.

Additionally, you must provide the following details:

  • Square version of your (the intermediary) logo in SVG or PNG format.

  • Callback URL where the partner will arrive after authorizing the link.

  • Name of the application which the partner grants access to connect.

When we receive this information you will receive an intermediary ClientID from us. You can use this when requesting the login page for the partner.

Code flow diagram

Our code flow requires you to go through a number of steps. Below is a schematic representation of these steps, which are further explained below:

Code flow

  1. /authorize?response_type=code&client_id=<clientId>&scope=offline_access+openid&redirect_uri=https://<callback_url>&state=<csrf_token>

  2. https://<callback_url>&state=<csrf_token>&code=<short_code>;

  3. Short code and csrf_token end up at 3rd party.

    • 3rd party confirms csrf_token to be identical to the one they initiated the request with.

    • Code is used to obtain access token

    • Client sends the Basic-auth header with client id + client secret (username/password)

    • POST /token, Authorization: Basic header, payload = code=<shortcode>&grant_type=authorization_code&redirect_uri=<callback_uri>

    • POST /token, Authorization: Basic header, payload = refresh_token=<refresh token>&grant_type=refresh_token

Set up intermediary authorization

Ask the partner to grant permission

  1. Ask the partner in your application to log in with their bol.com data. This prevents you from needing to ask for their API keys.

    This will lead them to a bol.com login page, similar to Google or Facebook SSO, where they can grant you permission to work with their account.

  2. For now you are free to use your own design for this page, but in future bol.com will introduce a style guide for this page.

Open the bol.com login page

Send the partner to the bol.com login page. You can include querystring parameters if desired. You can let the partner navigate to the following URL:

https://login.bol.com/authorize?response_type=code&client_id=<clientId>&scope=offline_access+openid&redirect_uri=https://<callback_url>&state=<csrf_token>&prompt=login

The following parameters are supplied in this URL:

  • response_type - always uses the value code

  • scope - here you need both offline_access and open_id

You must enter these parameters yourself:

  • clientId - we provide this for your use

  • callback_url - this is the URL in your application to which the partner will return if they have given permission in the bol.com environment.

  • csrf_token - this is a variable that you can fill and we will return to you afterwards

  • prompt - this should have prompt=login to force the user to log in. This is especially important if your user is already logged into the bol.com platform. Problems with sessions or cookies can be prevented if the user has more than one bol.com account.

Login page for partners

The example login page below uses Channable as the integrator:

Login page

The partner will log in with their bol.com data and come to a screen in which they must give permission for the request. In this screen we again use the logo and name for the application that you have given us.

Login confirmation page

In case of both acceptance and rejection of the login request, we will return the partner to the Callback URL you gave us.

In case of failure, you will receive an error and an error description from us in the URL:

https://<callback_url>&error=<error>&error-description=<description>

In the case of success, you will receive a shortcode from us in the URL and possibly a state if you have sent it to us yourself:

https://<callback_url>&state=<csrf_token>&code=<short_code>
The shortcode is only valid for 2 minutes.

Connect to our SSO API to gain access

Use the shortcode you received to connect to our SSO API endpoint and request an access token and a refresh token:

  • SSO API: https://login.bol.com/token

  • http-verb: POST

  • Headers: HTTP Basic Auth header with username=client-id and password=client-secret

Query parameters (mandatory)

  • grant_type: authorization_code

  • code: <shortcode>

  • redirect_url: <callback_url>

Response example

{
  "expires_in" : 599,
  "refresh_token" : "eyJhbGciOiJub25lIn0.eyJleHAiOjE1NTM5MzY4MTQsImp0aSI6IjZh   YmQ1NWNiLWFhOWQtNGM1Zi04OTczLWU5OTYwYjc4MmMyYiJ9.",
  "token_type" : "Bearer",
  "scope" : "offline_access",
  "access_token" : "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiIzMTM1NTAzNTciLCJvcmciOiJTTFI6MTIwNTU2NSIsImF6cCI6ImE3MDkyZDVjLWFlNTctNGY1MS1iNGM5LTg5YzBiMzY4ZGY2NyIsImlzcyI6Imh0dHBzOlwvXC9sb2dpbi5ib2wuY29tIiwic2NvcGVzIjoib2ZmbGluZV9hY2Nlc3MiLCJleHAiOjE1MjI0MDE0MTQsImlhdCI6MTUyMjQwMDgxNCwiYWlkIjoiQ1VTOjkwMDExOTMyODciLCJqdGkiOiI1MTUyZmI4OS0zYTRiLTRjZWItOTkxZC00ODFlNGZmYjk2MmIifQ.ZO06FK1Jp0LbVfvCPwgqwkrw8GNKE94kobtVfqlKVDmeHdtRKTI9UGVvdu1-r3y1dmgiGTijt_4EcNCfum9T9n1Vi71kOddqPyk_UAZR1_MT0DQ2Sfz6xSYMNPEqu_TkHZVg6Zk7xWL-HgIAAxP6usTBp6tyOH81I_2_6Jb_uyE"
}

Access token

The access token is valid for a maximum of 10 minutes. Once it expires you can use the refresh token to request a new access token. If you do this, the current access token becomes invalid and you receive a new one.

Refresh token

The refresh token is valid for one year. We advise our clients to re-log a month before expiration. To do this, add prompt=<login> as a query parameter.

You can find the expiration date in the refresh token by decoding it. This leads to the following format:

{
   "exp": 1553936814,
  "jti": "6abd55cb-aa9d-4c5f-8973-e9960b782c2b"
}

The exp field includes the expiration date of the consent in epoch.

Connect to the bol.com retailer API to start managing the partner’s offers and orders

When connecting to the bol.com Retailer API use the following header:

Authorization: Bearer <access_token>

You can now access any bol.com Retailer API endpoint on behalf of the partner.