Set up the Authorization Code Grant flow

Summary

Once your app has been added in your developer account and the Brightpearl account has been added as an early access account, a user of the Brightpearl account will need to approve the connection as part of the setup process.

This is done by directing the user to an approval page where they need to log into the Brightpearl account and confirm they want to authorize the connection.

This step is necessary in order to generate access tokens which allow successful API requests to be made.

OAuthscreen.png

To create this authorization flow, use the Authorization Code Grant. 

In brief:

  1. User clicks an “authenticate” button on your app or installs an app from Brightpearl app store. The user is directed to a Brightpearl managed URL along with information about what application is requesting access and where Brightpearl should redirect to once authorization is granted.
  2. If the user is not logged in to Brightpearl, they log in now. The user authorizes the application for access to their API, and the authorization server authenticates the user.
  3. The authorization server issues an authorization code to the application, and redirects the application to the redirect URI location specified in step 1 (which must also match the URI in your app settings).
  4. The application sends an HTTP request with the authorization code to the authorization server.
  5. The authorization server validates the authorization code and issues an access token which the application will use to access the Brightpearl API.

OAuthflow.png

The following section explains each step and how to set up the flow.

Setting up the Authorization Code Grant flow

1. User initiates

The user can initiate the workflow in one of two ways:

  • The user starts from a page within the new app (resource owner). This might be done by clicking an “Authorize” button from within the app configuration. This page is responsible for starting the OAuth flow for the user.
  • The user starts from within the Brightpearl app store. They click the “Turn on” button on the app in the app store.

In each case the user is directed to the install URL specified when the application was created in your developer account.

The application proceeds with the flow by redirecting the user to the authorization server using the following URL:

https://oauth.brightpearl.com/authorize/{account}?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&state={state}

The parameters are as follows:

  • account: the Brightpearl account that the application wants to access
  • client_id: the reference that you gave the app when creating it.
  • redirect_uri: this should be the same as the redirect URI you submitted when creating the app.
  • state: This should be a non guessable string that the authorization server will pass back to you on redirection which you should check against to prevent CSRF attacks

This will open a page which looks like this (assuming the user is already logged in - otherwise they will be prompted to login first):

OAuthscreen.png

2. User logs in and approves

The user logs in (if not already logged in) using their username and password and approves the application by clicking the "Approve" button.

3. Exchange of auth token for access token

Once access has been granted and the user authenticated, the authorization server issues an authorization token. It does this by appending the code to the redirect_uri provided and redirects the user to that URI. The redirect_uri will return the state that was sent in the initial request. We also include the account as a parameter in the URI, e.g.

HTTP/1.1 302 Found

Location:
https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz&account=outerheaven

The authorization code is the code parameter above. The state parameter’s value will be the same as the one provided in step 1 and must be validated. The code will expire either after 2 minutes or when it has been exchanged for an access code. If more than one attempt is made to exchange the authorization code for an access code then all issued access codes will be revoked.

The application now submits a request to exchange the authorization token for an access token.

Note that the request form must be sent via body and the encoding should be "application/x-www-form-urlencoded".

If either the client_secret or the code is sent in an insecure manner (e.g. via HTTP instead of HTTPS, within headers, or as URL query parameters), then the request will not be accepted.

POST https://oauth.brightpearl.com/token/{account}

Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}

The parameters are as follows:

  • account: the Brightpearl account that the application wants to access
  • code: the authorization code issued in step 3.
  • redirect_uri: this should be the same as the redirect URI you submitted when creating the app and sent in the authorization request.
  • client_id: this is the reference that you gave the app when creating it.
  • (optional) client_secret: if you have created a confidential app, this is the client secret which was issued to you upon app creation. Not required if the client type is public.

5. Store your access token

The authorization server will return the access token, its expires_in value and the refresh token which can be used to get a new access token once the access token has expired. The access_token is what will be used to make requests to the Brightpearl API. Note that we will additionally return the API domain for the account. You will need this when making API calls.

The following is an example response:

HTTP/1.1 200 OK

Content-Type: application/json
{
"access_token": "2YotnFZFEjr1zCsicMWpAA",
"token_type": "Bearer",
"expires_in": 604800,
"refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA",
"api_domain": "ws-eu1.brightpearl.com",
"installation_instance_id": "6"
}

The installation_instance_id returned in the response is Brightpearl’s identifier for the instance. Most applications will not need to know this information.

Making authenticated calls to the Brightpearl API 

Once you have your API token, you can use it to make calls the Brightpearl API. This is done by including your token in the Authorization header, preceded by “Bearer”. You should use the API domain for the account which was provided alongside the access token. You will additionally need you developer reference and account reference for the respective brightpearl-dev-ref and brightpearl-app-ref headers e.g.

GET
https://ws-eu1.brightpearl.com/public-api/{account}/product-service/product/1200
Content-Type: application/json
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
brightpearl-dev-ref: my-developer-ref
brightpearl-app-ref: my-app-ref

Installation instances 

It is possible to authorize and authenticate more than once for a single application. This is to enable scenarios where your application resides on more than one device, e.g. a mobile or native application, or if you want to allow multiple users to perform writes into Brightpearl under their own name (click “use staff identity” when creating the app). If your application is a single application running on a server, a single application instance will probably suffice.

Refreshing tokens

If the token has expired, you will receive a 401 HTTP status code. Upon receiving this, you must refresh your token to continue to access the API. When refreshing the token, you must also update the api_domain for the account to that returned in the refresh token response. We reserve the right to change the domain without notice. If we have changed the domain, you will receive a 401 for your API call and can then use the token refresh response to update it. The domain is thus migrated automatically with no disruption to service.

You can use the refresh_token to retrieve a new access_token. The refresh can only occur once the current token has expired, so you are required to wait until the access_token has expired to renew it with a new expiry time. Best practice is to set up a trigger based on receiving a 401 expiry code. As with initially requesting the access token, any sensitive information sent in an insecure manner will result in it being revoked. The payload is sent via the request body and the encoding can be either application/json or application/x-www-form-urlencoded.

POST https://oauth.brightpearl.com/token/{account}

Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}

The parameters are as follows:

  • account: the Brightpearl account that the application wants to access
  • refresh_token: the refresh token that was issued to the application instance.
  • client_id: the reference that you gave the app when creating it.
  • (optional) client_secret: If you have created a confidential app, this is the client secret which was issued to you upon app creation. Not required if the client type is public.

The following is an example response:

HTTP/1.1 200 OK

Content-Type: application/json
  {
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"Bearer",
  "expires_in": 604800,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "api_domain":"ws-eu1.brightpearl.com"
  }

Additional features

Our OAuth2.0 implementation conforms to the standard, but we have also made optional extensions to the standard to support common Brightpearl app use cases.

Using authorizing user’s identity (“Staff apps”) 

It is possible for all API actions (that support user auditing, i.e. ‘created by’ or ‘updated by’) performed by an application instance to be performed using the identity of the user that authorized the app (i.e. was logged in to Brightpearl when approving the installation)

This is useful for a mobile or desktop application where many different staff members have their own instance of the app installed on their device. It would not apply to, for example, automated data transfer tools, such as ecommerce connectors or exporters.

To use this feature, simply select “use staff identity” when creating the app.

Warning: It is not possible to change this option later.

Recovering application instances (advanced)

In a multi-instance application, instances can represent different things depending on your application design. An example is an ecommerce connector where each store you have on an ecommerce platform is a separate instance.

Some API resources in Brightpearl record which application instance was responsible for creating it. If you rely on this information but you lose your application tokens (or they are revoked for security reasons), this may present a problem: when you reauthorize the application, you will be given an entirely new instance, but you could have data captured by your app waiting to be sent to Brightpearl that can no longer be linked to the correct instance.

To work around this problem, initiate the application install process from the beginning, but later send additional parameters with your token exchange request to regain control of an existing instance. You will need to store the ‘installation_instance_id’ field from your initial OAuth token POST request. Refer to the ‘OAuth token POST’ API documentation for details.

Have more questions? Submit a request