Collection APIs are based on the OAuth 2 protocol, specifically, with refresh_token flow.

To get started, go to First Steps and register the Collection APIs you want to use.

Token Management

It is necessary to manage the access_token and refresh_token by your system so that the token never expires. If the refresh_token expires, you must access the platform BS2 Empresas and generate new token (see page First Steps).

We use a rate-limit in our authentication APIs that allows up to 10 access_token and refresh_token requests per minute.

The expires_in field represents the token's validity in seconds.

The refreshtoken has a longer validity time (48 hours) than the access_token validity (5 minutes in PRD and 7 minutes in HML). In other words, even if the access token is invalid and the _refresh_token is valid, it is still possible to run the refresh_token flow to generate a new, valid token.

When a new token is generated, the previous token is immediately invalidated.

It is important to emphasize that with each new token generated, a new refresh_token is also generated.

⚠️

Important:

When generating a new access_token, the existing key will be automatically invalidated, if it exists.

Refresh Token

To carry out the refresh token, follow the instructions:

1. Generate a new refresh_token on the BS2 Empresas platform https://app.empresashml.bs2.com/;
2. With the API Key, API Secret and Scope, create an HTTP POST request to the URL '/auth/oauth/v2/token';
3. In Body, use the values retrieved from the application to fill in the parameters below:
   1. scope with a value equal to the Scope obtained with the credentials;
   2. grant_type with text equal to refresh_token;
   3. refresh_token with value equal to the last valid refresh_token generated;
   4. client_id with client_id value;
   5. client_secret with value of client_secret;
4. Make the request and obtain the access_token.

To take a practical test, go here: Access Token/RefreshToken