API authentication for public apps

This page is for developers building apps for the Brightpearl app store. If you’re a Brightpearl customer building an app for your own use, or a developer working for a Brightpearl customer, see the private apps section to find out how to authenticate requests for private apps.

Authenticating system apps

When a Brightpearl customer installs your app, an unsigned account token is generated, unique to the relationship between your app and the customer’s account. There are three ways to get this token:

  • In your app’s configuration, supply an account install callback URI. The account code and unsigned account token will be sent to this URI when the customer installs your app. See Handling callbacks from Brightpearl  page for more details.
  • Use the installed installed account API to fetch a list of all the accounts that have your app installed, together with their unsigned account tokens.
  • In the developer services site, view a list of the customer accounts for your app.

Unsigned account tokens require signing using your developer secret. To sign an account token, create an HMAC-SHA256 hash of the unsigned account token, using your developer secret as the secret key. The result must be base64 encoded. Methods exist for generating these hashes in all popular programming languages.

If you are storing account tokens, we strongly recommend you store the unsigned account tokens only. If you lose your developer secret or it is compromised, a new one can be generated for you, and you will be able to use the new secret to sign all the existing account tokens, so the interruption to your service will be minimal. Additionally, storing signed tokens in your database is bad practice similar to storing your users’ passwords in plain text.

You will also need to determine the datacentre the customer’s account is hosted on to build the API URL. We’ve provided the Account Access API for this purpose; see our API docs for information on this and how to build an API URL .

Once you have a customer’s account code, datacentre, and signed account token, you’re ready to make an API call. To authenticate the request, add the following headers:

brightpearl-dev-ref: {developer reference}
brightpearl-app-ref: {app reference}
brightpearl-account-token: {signed account token}

To summarise, when making an API call to a Brightpearl customer’s account, you will need the following information:

 OriginUse
Customer account code From install callback or installed accounts API In URL path
Customer datacentre From the account access API In URL host
Unsigned account token From install callback or installed accounts API Raw form of account token
Developer reference Chosen when you registered In request headers
Developer secret Generated when you registered To sign the account token
App reference Chosen when you created the app In request headers

Example:

Customer account code topfurniture
Customer datacentre eu1
Unsigned account token c72a9373-86f5-4138-a41f-c26cd9abfe4e
Developer reference sahara
Developer secret fcVGPrRapgRyT83CJb9kg8wBpgIV7tdKikdKA/7SmvY=
App reference parcelforce

Given values as shown in the table above, to request a set of products, the API request would be:

GET https://ws-eu1.brightpearl.com/public-api/topfurniture/product-service/product/1000-1010
brightpearl-dev-ref: sahara
brightpearl-app-ref: parcelforce
brightpearl-account-token: xOcgfoSsTBnWVAHr46EIWpA5U+/mpflsts/lF7p2jnc=

You can test your token signing algorithm using the data above, i.e. signing c72a9373-86f5-4138-a41f-c26cd9abfe4e with fcVGPrRapgRyT83CJb9kg8wBpgIV7tdKikdKA/7SmvY= as the key should output xOcgfoSsTBnWVAHr46EIWpA5U+/mpflsts/lF7p2jnc= . We recommend using https://quickhash.com/ to verify your results online.

Authenticating staff apps

Staff apps are an extension of system apps, so all the information in the section above applies to staff apps as well. This section describes how to fetch a staff member’s authentication token from a Brightpearl account, and how to use this to authenticate requests instead of an account token.

Staff authentication tokens are generated when an administrator of a Brightpearl account authorises one of their staff to use your app. There is no callback for this event - developers are not given staff tokens until that staff member supplies either the token or their email address and password, for example when logging into your app.

Note that staff authentication does not require your developer secret, or signed account tokens. This means it’s safe to implement in a mobile or desktop app where your code could be decompiled.

Fetching staff tokens

Staff can view a list of the apps they’re authorised to use when they log in to Brightpearl. Their staff tokens are also shown, so you can choose to ask for this token in your app. However we also provide an API that accepts a staff member’s email address and password, and returns their staff token if your app has been installed in the account and the staff member is authorised to use it.

You will need the customer account code and datacentre, and the staff email address and password to call the staff authorise API. For this call you only need to provide your developer and app references, not an account token.

The staff token returned by this API is ready for use; it does not require signing with your developer secret.

Example:

Customer account code topfurniture
Customer datacentre eu1
Developer reference sahara
App reference parcelforce
Staff email katie@topfurniture.com
Staff password 0p3nSE5AME

Given values as shown in the table above, to fetch the staff token for this user the request would be as follows:

POST https://ws-eu1.brightpearl.com/topfurniture/authorise
brightpearl-dev-ref: sahara
brightpearl-app-ref: parcelforce
content-type: application/json

{
	"apiAccountCredentials": {
    		"emailAddress": "katie@topfurniture.com",
    		"password": "0p3nSE5AME"
	}
}

The response looks like this:

{
  "response": "QJURscX/aYZL0N2cNLdrSBAtjEXEgeVaWgUz/JmPUtE="
}

Authenticating staff API requests

The authentication headers for a staff API request are very similar to those for a system request, but instead of sending an account token, you need to send the staff token. The required headers are:

brightpearl-dev-ref: {developer reference}
brightpearl-app-ref: {app reference}
brightpearl-staff-token: {staff token}

Example:

Using the values given in examples above, a staff API request for products would be as follows:

GET https://ws-eu1.brightpearl.com/public-api/topfurniture/product-service/product/1000-1010
brightpearl-dev-ref: sahara
brightpearl-app-ref: parcelforce
brightpearl-staff-token: QJURscX/aYZL0N2cNLdrSBAtjEXEgeVaWgUz/JmPUtE=
 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.