API authentication for private apps

This page is for Brightpearl account owners who want to build their own apps, and developers working for a Brightpearl account owner. If you’re a developer building an app for the Brightpearl app store, please see the registered developer section .

Authenticating private system apps

When you create a private app, an account token is generated. Keep this token safe; it grants access to your account using the API, so it should be stored somewhere secure. The account token is unique to the app, so you can revoke the token by disabling the app without affecting any other apps.

To authenticate an API request, add the following headers:

brightpearl-app-ref: {app reference}
brightpearl-account-token: {account token}

When making an API call to your account, you will need the following information:

  Origin Use
Your account code Used when you log in to Brightpearl In URL path
Your datacentre See the URI syntax page In URL host
App reference Chosen when you created the app In request headers
Account token Generated when you created the app In request headers

Example:

Your account code topfurniture
Your datacentre eu1
App reference topfurniture_autoship
Account token xOcgfoSsTBnWVAHr46EIWpA5U+/mpflsts/lF7p2jnc=

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-app-ref: topfurniture_autoship
brightpearl-account-token: xOcgfoSsTBnWVAHr46EIWpA5U+/mpflsts/lF7p2jnc=

Authenticating private 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 your account, and how to use this to authenticate requests instead of an account token.

Staff authentication tokens are generated when you authorise your staff to use your app. Each staff member has their own token so their authorisation can be revoked at any time.

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. We also provide an API that accepts a staff member’s email address and password, and returns their staff token if they are authorised to use the app.

For this API call you only need to provide your app reference, not an account token.

Example:

Your account code topfurniture
Your datacentre eu1
App reference topfurniture_autoship
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-app-ref: topfurniture_autoship
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-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-app-ref: topfurniture_autoship
brightpearl-staff-token: QJURscX/aYZL0N2cNLdrSBAtjEXEgeVaWgUz/JmPUtE=
 
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.