Consent
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:
- Make a
Basic Auth
request on the above endpoint with the application's API Key and API Secret; - Enter the code description in the
response_type
field; - Enter the scope of the application in the
scope
field; - The
state
field is free to identify the client/user; - 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:
Name | Located in | Mandatory |
---|---|---|
code | query | Yes |
state | query | Yes |
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:
- Make a
Basic Auth request
on the above endpoint with the application's API Key and API Secret; - Enter the
authorization_code
amount for thegrant_type
field; - Enter the authorization code received in the
code
field; - 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
- Make a
Basic Auth
request on the endpoint below with the application'sapikey
andapisecret
; - Enter the refresh_token amount for the
grant_type
field; - Enter the scope of the application in the
scope
field; - 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
Updated 11 months ago