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:
-
/authorize?response_type=code&client_id=<clientId>&scope=offline_access&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 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.
-
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=loginThe following parameters are supplied in this URI:
-
response_type- always uses the valuecode -
scope- here you needoffline_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 haveprompt=loginto 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:
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.
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.