OAuth Token POST
URI
https://{DATACENTER}.brightpearlconnect.com/oauth/token Description
This endpoint uses a different protocol to our other API endpoints. It follows OAuth2.0 specifications. Specifically, it grants a token in accordance with the access token request steps of OAuth 2.0 authorization grant flows.
The main differences this has from our other endpoints are as follows:
- Input data is x-www-form-urlencoded rather than application/json
- Although the response body is in JSON, its keys are underscore-cased instead of camel-cased.
The parameters sent to this endpoint depend on the authorization flow you are using. The parameters required are specified in the sections below.
As the request is x-www-form-urlencoded, you must URL-encode all parameter values. Failure to do so will result in intermittent failures due to tokens being generated with special characters.
On top of the usual OAuth2.0 parameters, you must also supply your account code. This can be specified in request body as account_code. Alternatively you can access this endpoint at /{account}/oauth/token. This is useful if you are using an OAuth client which will not allow custom request parameters.
Grant flows
Authorization code grant
| parameter | description | example | notes |
|---|---|---|---|
| grant_type | Must be set to authorization_code | grant_type=authorization_code | |
| code | The authorization code | code=SplxlOBeZQQYbYS6WxSbIA | This is received by your application in the callback from the Brightpearl authorization endpoint. |
| client_id | The integration ref of the integration attempting to obtain the token. | client_id=an-integration | |
| client_secret | The integration's client secret | client_secret=xXewetokdZpxIq1FZ1gasAQvEJksVImq%2FgkBJZ9u67g%3D | This is only required if the integration has confidential OAuth enabled. |
| redirect_uri | The redirect URI used to obtain the authorization code | redirect_uri=https%3A%2F%2Fredirect.integration.com%2Fauthorized | This must be identical to the redirect URI registered for the integration. |
| account_code | The account that the token is valid against. | account_code=indosports | Can also be specified in the URL, e.g. /indosports/oauth/token |
Token refresh
| parameter | description | example | notes |
|---|---|---|---|
| grant_type | Must be set to refresh_token. | grant_type=refresh_token | |
| refresh_token | The refresh token previously granted. | refresh_token=sq0QzvQ%2Fyd%2B93rmRyhJugD79GKVKPB2JCBmOSth18mM%3D | |
| client_id | The integration ref of the integration attempting to refresh the token. | client_id=an-integration | |
| account_code | The account that the we are refreshing the token for. | account_code=indosports | Can also be specified in the URL, e.g. /indosports/oauth/token |
Response
The response body contains the following properties:
| property | description | example | notes |
|---|---|---|---|
| access_token | The access token | u9+uX6ZxQCwU8w6dMYnPYr4dOE4+8ZUk1CZV2sOQaA8= | |
| refresh_token | The refresh token | agutoaXW4z7CchZPgbMceNyvxOVrt2j5Psqj871+0Y4= | |
| token_type | The type of token granted (Bearer) | Bearer | |
| expires_in | The lifetime in seconds of the access token | 604800 | |
| installation_instance_id | The ID integration instance associated with this token | 65 | This ID does not change when the token is refreshed, and is not returned for grant_type=refresh_token. |
| api_domain | The API domain to use for subsequent API requests with this access token | ws-eu1.brightpearl.com | This might change when the token is refreshed, so should always be updated. This enables an easy mechanism for migrating accounts between datacenters by simply invalidating existing access tokens. |
Instance recovery
Obtaining an access token creates a new integration instance for the authorized integration. This means that when a token is revoked or lost by the integration, a new integration instance will be created. For certain integrations this might not be acceptable. For example, there might be a lot of manual configuration associated with the instance, or it might be a partially offline app which has collected data offline which it now cannot transmit back to Brightpearl.
To support this use case, instance recovery is supported by all our grant types (except refresh_token for which it isn't relevant). You must supply the both of the following additional parameters in the request:
| previous_instance_id | The ID of the instance you wish to recover |
| previous_access_token | The last known access token for this instance |
If the previous ID and access token are recognized then the existing instance will be authorized. Otherwise, an HTTP 400 response will be returned and no new instance will have been created.
Instances may only be recovered by the integration which originally created them.
Note that instances created before the introduction of instance recovery in Jan 2018 will not have any previous access tokens stored, and therefore cannot be recovered.
Example 1
Obtain a token for account "indosports" using confidential auth integration "an-integration" via the authorization code flow
Request URI
/indosports/oauth/token
Request body
grant_type=authorization_code&code=2c66fc2f-4c97-44a7-a8fe-3f332629ac51=&client_id=an-integration&client_secret=xXewetokdZpxIq1FZ1gasAQvEJksVImq/gkBJZ9u67g=&redirect_uri=https%3A%2F%2Fredirect.integration.com%2FauthedResponse
{
"expires_in": 604800,
"token_type": "Bearer",
"refresh_token": "sq0QzvQ/yd+93rmRyhJugD79GKVKPB2JCBmOSth18mM=",
"access_token": "frR0feR7Pkqgmj3eLM5w0QE/7fAIBG+4U/pwro9Tnd0=",
"installation_instance_id": "68",
"api_domain": "ws-eu1.brightpearl.com"
}Example 2
Obtain a token for account "indosports" using public auth integration "an-integration" via the authorization code flow
Request URI
/indosports/oauth/token
Request body
grant_type=authorization_code&code=2c66fc2f-4c97-44a7-a8fe-3f332629ac51=&client_id=an-integration&redirect_uri=https%3A%2F%2Fredirect.integration.com%2FauthedResponse
{
"expires_in": 604800,
"token_type": "Bearer",
"refresh_token": "sq0QzvQ/yd+93rmRyhJugD79GKVKPB2JCBmOSth18mM=",
"access_token": "frR0feR7Pkqgmj3eLM5w0QE/7fAIBG+4U/pwro9Tnd0=",
"installation_instance_id": "68",
"api_domain": "ws-eu1.brightpearl.com"
}Example 3
Refresh a token for account "indosports" using integration "an-integration"
Request URI
/oauth/token
Request body
grant_type=refresh_token&refresh_token=sq0QzvQ%2Fyd%2B93rmRyhJugD79GKVKPB2JCBmOSth18mM%3D&client_id=an-integration&account_code=indosportsResponse
{
"expires_in": 604800,
"token_type": "Bearer",
"refresh_token": "q+HTLamZmAO3a/48bKDumGA2hP0osvA88qS6GdjFxNU=",
"access_token": "SnFZZOy3UrSY+DjlRd1xXlrIOegzNInNfld3qbKOErM=",
"api_domain": "ws-eu1.brightpearl.com"
}Example 4
Obtain a token for account "indosports" and existing instance 68 using public auth integration "an-integration" via the authorization code flow with instance recovery
Request URI
/indosports/oauth/token
Request body
grant_type=authorization_code&code=2c66fc2f-4c97-44a7-a8fe-3f332629ac51=&client_id=an-integration&redirect_uri=https%3A%2F%2Fredirect.integration.com%2Fauthed&previous_instance_id=68&previous_access_token=SnFZZOy3UrSY+DjlRd1xXlrIOegzNInNfld3qbKOErM%3DResponse
{
"expires_in": 604800,
"token_type": "Bearer",
"refresh_token": "sq0QzvQ/yd+93rmRyhJugD79GKVKPB2JCBmOSth18mM=",
"access_token": "frR0feR7Pkqgmj3eLM5w0QE/7fAIBG+4U/pwro9Tnd0=",
"installation_instance_id": "68",
"api_domain": "ws-eu1.brightpearl.com"
}