Authentication
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:
- Make a Basic Auth request on the endpoint below;
- Set the _password _value for the field
grant_type
; - Set the onboarding-pj value for the
scope
field; - Inserir usuário e senha válidos nos campos de
username
epassword
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
Name | Located in | Description | Required |
---|---|---|---|
grant_type | body | Defines the type of request | Yes |
scope | body | Defines the scope of the request | Yes |
username | body | Enter a user previously registered in the BS2 Bank | Yes |
password | body | Enter a valid password for the user entered in the field above | Yes |
Answer
Code | Description |
---|---|
200 | Success |
400 | Bad Request |
401 | Unauthorized |
SANDBOX | PRODUCTION | |
---|---|---|
Requests | Request URL from the BS2 team | Request URL from the BS2 team |
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.
- Generate a token using
ClientId
,ClientSecret
,username
andpassword
. Token generation flow described in the step above. The token has an expiration date of seconds, presented in the fieldexpires_in
. 420 seconds in Sandbox and 300 seconds in Production; - 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;
- 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:
- Make a Basic Auth request on the endpoint below;
- Set the refresh_token value for the field
grant_type
; - Set the onboarding-pj value for the
scope
field; - 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
Name | Located in | Description | Required |
---|---|---|---|
grant_type | body | Defines the type of request | Yes |
scope | body | Defines the scope of the request | Yes |
refresh_token | body | Insert the previously received refresh token | Yes |
Answer
Code | Description |
---|---|
200 | Success |
400 | Bad Request |
401 | Unauthorized |
The token refresh flow eliminates the need to enter username and password when obtaining a new authentication token.
Updated 6 months ago