Intermediary authorization on behalf of partners

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


This flow is only available for intermediaries who participate in the 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:

Code flow

  1. /authorize?response_type=code&client_id=<clientId>&scope=offline_access+openid&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 data. This prevents you from needing to ask for their API keys.

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

Open the login page

Send the partner to the login page. You can include querystring parameters if desired. You can let the partner navigate to the following URI:<clientId>&scope=offline_access+openid&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 both offline_access and open_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 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 platform. Problems with sessions or cookies can be prevented if the user has more than one account.

Login page for partners

The example login page below uses Channable as the integrator:

Login page

The partner will log in with their 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 URI you gave us.

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


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:

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:

  • 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.

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

When connecting to the Retailer API use the following header:

Authorization: Bearer <access_token>

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