The partner must make the OAuth 2 screen available to the checking account holder for authentication. To do this, it is necessary to make a GET request in the /api-banking/auth/oauth/v2/authorize method, as per the steps:

1. Make a Basic Auth request on the above endpoint with the application's API Key and API Secret;
2. Enter the code description in the response_type field;
3. Enter the scope of the application in the scope field;
4. The state field is free to identify the client/user;
5. Enter the endpoint used to receive the authorization code in the redirect_uri field.

Checking account holder authentication

When accessing the consent URL with valid parameters presented by the partner, the Banco BS2 checking account holder will be redirected to a login screen in the Banco BS2 environment:

After validating the checking account holder's username and password, confirmation of consent will be requested with a second authentication factor, app token or SMS token:

With the token validated, we will redirect to your endpoint with the authorization code.

The redirect_uri must be GET and be prepared to receive the following parameters:

📝

Note:

The code parameter is mandatory to perform authentication in the next step Partner authentication on the holder's account

Partner authentication on the holder's account

To obtain the access_token and Refresh_token from this code, the authorization code flow must be done, accessing the POST /auth/oauth/v2/token method, as per the steps:

1. Make a Basic Auth request on the above endpoint with the application's API Key and API Secret;
2. Enter the authorization_code amount for the grant_type field;
3. Enter the authorization code received in the code field;
4. Enter the endpoint used to receive the authorization code for the redirect_uri field.

Token Management

It is necessary to manage the access_token and refresh_token within the partner's system.

The refresh_token has a longer validity period than the access_token, that is, even if the access_token is expired, the refresh_token is valid for 30 days.

When the token is close to expiration, a new token must be generated using a refresh_token. To do so, receive a new token valid for the same period. It is important to emphasize that for each new token generated, a new refresh_token is also generated.

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

⚠️

Important:

• If the refresh_token expires, it will be necessary to redo the complete consent flow;
• There is no limit on requests while the token is valid;
• The access token is required for all requests to our APIs.

Refresh Token

1. Make a Basic Auth request on the endpoint below with the application's apikey and apisecret;
2. Enter the refresh_token amount for the grant_type field;
3. Enter the scope of the application in the scope field;
4. Enter the amount of the refresh_token previously received for the refresh_token` field.

To carry out a practical test, access here: Access Token/RefreshToken