APIs are authenticated with the information of a pair of tokens in the requests’ header: The following pair of tokens is expected in each request:
client_id: client’s access identification. This token is generated through a quick registration in the logged area of this portal.
access_token: it stores the access rules allowed for the client_id. This token may be obtained procedurally, for any environment, by following authentication flow OAuth2.
Transfer Protocol
All transfer of information circulated by the APIs occurs through the HTTPS protocol, which ensures a safe channel and waives token encryption manually.
OAuth 2
OAuth2 is a broadly-used authentication standard, which does not allow its application to manipulate user names and passwords directly. Companies like Google, Facebook and Twitter already use this standard to provide their resources with a safe access to third parties’ applications.
Next, you can check the necessary steps to complete the OAuth2 integration process:
1. Obtaining Client ID and Client Secret
In our logged area, you must register to obtain the client_id and client_secret that will be needed in the OAuth flow.
2. Obtaining the Access Token
After obtaining the client_id and the client_secret, it is time to exchange them for the access_token, which will give access to ANBIMA’s APIs.
In fact, the request below must be made for our Oauth API:
POST
https://api.anbima.com.br/oauth/access-token
HEADER
Content-Type: application/json
Authorization: Basic base64(client_id:client_secret)
REQUEST BODY
{
"grant_type": "client_credentials"
}
The information provided to Authorization field must be base-64 encoded. Therefore, to generate the Authorization header of the pair client_id = aC2yaac23 e client_secret = 1bhS45TT, for instance, base-64 of string aC2yaac23:1bhS45TT, must be generated, which will result in key YUMyeWFhYzIzOjFiaFM0NVRU. So, the header would be: ‘Authorization’: ‘Basic YUMyeWFhYzIzOjFiaFM0NVRU’.
After this call, the following reply will be obtained from OAuth 2.0 API:
{
// O access_token gerado deve ser armazenado para ser utilizado nas chamadas à API
"access_token": "222rkya88",
"token_type": "access_token",
"expires_in": 3600
}
In the response, the expiration time for the access_token. is indicated in seconds. After its expiration, the same procedure above shall be repeated to obtain a new token.
3. Requests to API
Now that the access_token has been obtained, its application may finally make calls requests to the API by using the Sandbox and Production endpoints.
| Production URL | Sandbox URL |
| https://api.anbima.com.br | https://api-sandbox.anbima.com.br |
Authentication Errors
Some errors can be handled during Tokens authentication dealt with during the authentication of the Tokens (client_id e access_token). List of errors:
| Code | Type of error | Description |
| 401 | Inexistent/wrong token | If any Token obtained doesn’t exist or has any error (if it has been changed), error 401 ‘Unauthorized’ will be returned. |
| 403 | Revoked (invalid) Tokens or API resources unavailable for the plan contracted at ANBIMA | If any Token was revoked, it will be considered invalid and error 403 ‘Forbidden’ will be returned. Likewise, if the resource accessed is not allowed for the contracted plan, the same error will be returned. |
For errors regarding the absence of one of the tokens and/or due to a wrong/inexistent token, some measures may be taken by the developer to validate whether the information being provided is valid. For errors of revoked (invalid) tokens, the only possible action is to request a new token.