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 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
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:
-
/authorize?response_type=code&client_id=<clientId>&scope=offline_access+openid&redirect_uri=https://<callback_uri>&state=<csrf_token> -
https://<callback_uri>&state=<csrf_token>&code=<short_code>; -
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
-
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.
-
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 URI:
https://login.bol.com/authorize?response_type=code&client_id=<clientId>&scope=offline_access+openid&redirect_uri=https://<callback_uri>&state=<csrf_token>&prompt=loginThe following parameters are supplied in this URI:
-
response_type- always uses the valuecode -
scope- here you need bothoffline_accessandopen_id
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.com environment. -
csrf_token- this is a variable that you can fill and we will return to you afterwards -
prompt- this should haveprompt=loginto 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:
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.
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
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_uri: <callback_uri>
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.