Intermediary authorization on behalf of partners

Intermediaries who participate in bol’s Intermediary Partner Program can offer partners the opportunity to log in by entering their bol account details. This route makes it easier for partners to connect their own systems to bol and removes the need for the partner to request and enter API keys. It also provides bol 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 Intermediary Partner Program.

Additionally, you must provide the following details:

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

  • Callback URI 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

Please avoid passing sensitive information: such as client secrets, access tokens, or refresh tokens, in URL query parameters. Requests with these details in the URL will be rejected.

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&redirect_uri=https://<callback_uri>&state=<csrf_token>

  2. https://<callback_uri>&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 data. This prevents you from needing to ask for their API keys.

    This will lead them to a bol 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 will introduce a style guide for this page.

Open the bol login page

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

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

The following parameters are supplied in this URI:

  • response_type - always uses the value code

  • scope - here you need offline_access

You must enter these parameters yourself:

  • clientId - we provide this for your use

  • callback_uri - this is the URI in your application to which the partner will return if they have given permission in the bol 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 platform. Problems with sessions or cookies can be prevented if the user has more than one bol account.

Login page for partners

The example login page below uses Channable as the integrator:

500

The partner will log in with their bol 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.

500

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

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

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

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

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

Connect to our SSO API to gain access

Request set of Tokens

To request the tokens (accessToken and refreshtoken if applicable), send a POST request to the following URI:

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>
Header Name Value

Content-Type

application/x-www-form-urlencoded

Accept

application/json

Authorization

Basic {base64-encoded clientId:xlientSecret}

POST Body Parameters

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

Parameter Value

grant_type

authorization_code

code

<shortcode>

redirect_uri

<callback_uri>

Response example

{
  "expires_in" : 599,
  "refresh_token" : "eyJhbGciOiJub25lIn0.eyJleHAiOjE1NTM5MzY4MTQsImp0aSI6IjZhYmQ1NWNiLWFhOWQtNGM1Zi04OTczLWU5OTYwYjc4MmMyYiJ9.",
  "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.

With the refreshtoken a new set of tokens (accessToken and refreshToken if applicable) can be requested, without signing in again:

Method: POST

Headers:

Header Name Value

Content-Type

application/x-www-form-urlencoded

Accept

application/json

Authorization

Basic {base64-encoded clientId:clientSecret}

POST Body:

Parameter Value

grant_type

refresh_token

refresh_token

<refreshtoken>

Response example

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

Keep in mind that you will receive a new refreshtoken.

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

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

Authorization: Bearer <access_token>

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