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.



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;
  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