OAuth authentication

Introduction

OAuth was introduced to Brightpearl in August 2019 and replaces all previous authentication methods, which will soon be deprecated. All new apps should use OAuth.

At Brightpearl we use OAuth2.0 as the workflow for authorizing applications. Currently we use the Authorization Code Grant flow for all Instance application types. To understand Oauth Authorization Grant Flow we have to go through a few definitions.

Roles

There are four role definitions in OAuth:

Resource Owner

This is the end user who will authorize your application for access. In Brightpearl this is a staff member in a particular brightpearl account.

Resource Server

This is the server hosting the protected resources. The server accepts and responds to requests protected resources using access tokens. In Brightpearl this is our API.

Client

The client is the application making the requests on behalf of the resource owner and with its authorization. The term “client” does not make any assumptions about the type of application or device that is making the requests. It could be a mobile device, code running on a server, desktop application, etc.

Authorization Server

This is the server which issues the access tokens to the client after the authenticated resource owner has granted authorization. In Brightpearl this is our API gateway

Client Types

There are two client (application) types defined in OAuth. These are determined by the client’s ability to maintain confidentiality of their client credentials.

Confidential

Clients capable of maintaining the confidentiality of their credentials (e.g., client implemented on a secure server with restricted access to the client credentials), or capable of secure client authentication using other means.

Public

Clients incapable of maintaining the confidentiality of their credentials (e.g., clients executing on the device used by the resource owner, such as an installed native application or a web browser-based application), and incapable of secure client authentication via any other means.

Application registration 

The first thing you’ll need to do if you haven’t already is register yourself as a developer.

Next you will need to create your application. It will need to be an Instance app to use OAuth authentication.

There are a few fields that require attention when creating your application:

Redirect URI (required)

This is the absolute URI that the authorization server will redirect the user-agent to once it has granted the application access.

Client type (required)

This determines the authorization mechanism for the application. The visibility can either be confidential or public. If your application is confidential then upon creating the app you will be issued a client secret.

Account install URL (optional)

This is the URL of your application that brightpearl will direct the user to to initiate the installation of the application, when they choose “install” from the Brightpearl app store..

Account uninstall URL (optional)

This callback URL will be called when the user uninstalls your application. Consider using this to start a subscription cancellation process, or account deprovisioning process.  If an app is uninstalled from Brightpearl, you will no longer be able to make API calls for that account.

Use staff identity

This field allows the app to perform API actions using the identity of the user that authorized the installation. See the later section Using authorizing user’s identity (“Staff apps”)

Authorization code grant

The Authorization Code Grant looks like this:

OAuthflow.png

Broken down into steps this goes as follows:

  1. User clicks “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 on authorization.
  2. If user is not logged in to Brightpearl, they log in now. The user authorizes the application for access to their API, the authorization server authenticates the user
  3. The authorize server issues the application an authorization code 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.

In more detail these steps are:

1. Begin flow

The flow can begin in two ways

  1. The user starts from a page managed by the resource owner (application). This page is responsible for starting the OAuth flow for the user.
  2. The user starts from within Brightpearl app store. They press the “Turn on” button on the application entry. This sends the user to the application install URL specified when the application was created in the app store.

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 params 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 log in

The user logs in (if not already logged in) using their username and password and approves the application.

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 param above. The state param’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 params), 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=

The params 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.
  • 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 occur at any time, so you do not have to wait until the access_token has expired to renew it with a new expiry time. 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 params 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.
  • 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. 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