When creating an app you will need to specify the type of app. Instance, staff and system apps use different methods of authentication so it’s important to understand and choose the correct one.
All new apps should be an Instance app, using the OAuth mechanism for authentication. When a user installs the app, an Auth token is given to the application to make subsequent API calls.
If the app needs to be able to perform reads and writes into Brightpearl as a given user (rather than anonymous), an instance app can have multiple instances, each of which is authenticated by a different user.
The authentication method for system apps will soon be deprecated.
System apps authenticate with a Brightpearl customer’s account using credentials that identify the developer and the app, and prove that the app is authorized to use the account. API calls by the app are made on behalf of the app itself, not any staff member, so there is never any need to supply a staff member’s email address or password to the developer.
Typically a system app is a hosted service running on servers controlled by the developer. For most apps, the actions the service performs on the customer’s account will be scheduled, or a consequence of some event in the account or a third party system (for example a payment provider or marketplace).
The authentication method for staff apps will soon be deprecated.
Staff apps are an extension of system apps. They provide the same method of authenticating as a hosted service with the customer’s account, but add support for an authorized staff member to use their own email address and password to authenticate with the API.
Staff authentication is well suited to desktop and mobile apps, where individual staff members have the app running on their own computer or phone. For these apps it would be a security risk for the developer to store their credentials in the code.
In addition, staff apps allow control over which members of staff are permitted to use the app. Each staff member must be individually authorized to use an app by their account administrator. This authorization can be revoked at any time, without affecting other users.
Staff apps may still have a hosted service run by the developer. This could be used to support a mobile or desktop app, for example by receiving webhook callbacks from Brightpearl and sending push notifications to the devices.