Before having access to the production environment of the BS2 Bank API, it is necessary to carry out the homologation process in our sandbox environment. To access the sandbox environment, please contact us at [email protected]

📝

Note:

We use a rate-limit in our authentication APIs, which allows up to 10 token requests and refresh per minute, requiring token management.

Authentication Token

To use the API, you need to obtain the authentication token linked to a BS2 user. To issue the access token, reproduce the following steps:

1. Make a Basic Auth request on the endpoint below;
2. Set the _password _value for the field grant_type;
3. Set the onboarding-pj value for the scope field;
4. Inserir usuário e senha válidos nos campos de username e password

POST /auth/oauth/v2/token

{
  "grant_type":"password",
  "scope":"onboarding-pj",
  "username":"valid_username",
  "password":"valid_password"  
}

{
  "access_token": "seu_access_token_guid",
  "token_type": "tipo_de_token",
  "expires_in": "tempo_de_expiracao_em_segundos",
  "refresh_token": "seu_refresh_token_guid",
  "scope": "onboarding-pj"
}

Parameters

Answer

⚠️

Important:

The authentication token is required for all requests in our APIs. Pay attention to the expiration time (in seconds) informed in the return of your request. Manage your application so that it refreshes the token before its expiration as per the following flow.

Token Management

You need to manage access_token and refresh_token within your application.

1. Generate a token using ClientId, ClientSecret, username and password. Token generation flow described in the step above. The token has an expiration date of seconds, presented in the field expires_in. 420 seconds in Sandbox and 300 seconds in Production;
2. Using the refresh_token generated in the previous step, you must make the _refresh_token _flow. In this way, you should not use username and password to generate a new token;
3. Before the refresh_token expires (10 minutes long), you need to renew the token using the refresh_token flow.

Important Points

When generating a token using username and password, you should only generate new tokens using the refresh_token flow (using the refresh_token and not the username and password).

It is only necessary to generate a new token, using username and password, if you are unable to perform the refresh_token flow.

The expires_in field represents the validity of the token in seconds, as long as the token is valid, this token should be used.

The refresh_token has a validity time longer than the validity of the token (10 min), that is, even if the token is invalid for time, and the refresh_token is valid, it is still possible to do the refresh_token flow to generate a valid token.

When the token is close to expiration, a new token must be generated, using a refresh_token, in order to receive a new token valid for the same period.

There is no limit to the number of requests as long as the token is valid.

When a new token is generated, the previous token becomes invalid.

Token Update

After generating an authentication token, it is recommended that its expiration time be managed by the token refresh flow according to the following steps:

1. Make a Basic Auth request on the endpoint below;
2. Set the refresh_token value for the field grant_type;
3. Set the onboarding-pj value for the scope field;
4. Set the value of the previously received refresh_token for the field refresh_token.

{
  "grant_type": "refresh_token",
  "scope": "onboarding-pj",
  "refresh_token": "refresh_token"
}

{
  "access_token": "seu_access_token_guid",
  "token_type": "tipo_de_token",
  "expires_in": "tempo_de_expiracao_em_segundos",
  "refresh_token": "seu_refresh_token_guid",
  "scope": "onboarding-pj"
}

Parameters

Answer

The token refresh flow eliminates the need to enter username and password when obtaining a new authentication token.