🔐 Authentication

The Liber Capital API implements the OAuth 2.0 Authorization. This authorization framework is a protocol that allows a user to grant a third-party web site or application access to the user's protected resources, without necessarily revealing their long-term credentials or even their identity.

For the scope of these APIs, client-credentials flow will be the only one available, of which is used for machine-to-machine communication.

Rate Limit

Our Authentication API have a rate limit of 4 (four) tokens per minute. It`s a security policy that help us to identify and block DDoS atacks. We will block for a few minutes any CLIENT ID that send more than the limit.
To avoid this, you will need to implement a cache for your token and control the expire time of it.

Client Credentials Flow

With machine-to-machine (M2M) applications, such as CLIs, daemons, or services running on your back-end, the system authenticates and authorizes your application rather than a user.
Therefore, M2M apps must use the Client Credentials Flow (defined in OAuth 2.0 RFC 6749, section 4.4), in which they pass along their Client ID and Client Secret to authenticate themselves and get a access-token.

Our authorizer generates access-tokens for API authorization scenarios, in JSON web token (JWT) format. The permissions represented by the access token, in OAuth terms, are known as scopes. If those scopes are authorized for the client credential, then the access token will represent these authorized scopes.

Step-by-step

First, you need to request a Client ID and Client Secret to [email protected], the credentials for the staging environment will be sent to you.
With the credentials, you will be able to generate the tokens to access our APIs services.
For example :

The following are the relevant HTTP requests:

POST https://api.bavabank.com/oauth2/access-token

Content-Type: application/json
{
  "audience": "<API_IDENTIFIER>",
  "grant_type": "client_credentials",
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>"
}

Note: The audience field is the URL that refers to the content that will be accessed by the generated token.

For example :

"audience": "https://api.stg.bavabank.com/pix/v1/",

The authorization server validates the request, and, if successful, sends a response with an access token.:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 86400
}

Now you're ready to develop the integration as well as testing your business use case, like creating vendors accounts and generating customers invoices.