Skip to main content

Authentication

The API uses OAuth 2.0 with the client_credentials grant. You exchange a client_id and client_secret for a Bearer token, then send that token on every request.

Getting credentials​

Credentials are issued through the Customer Portal:

  1. Log in to the portal and open the Integrations section.
  2. Click New Credentials to generate a client_id and client_secret.
  3. Copy the client_secret immediately — it is partially masked once the modal closes.

Store both in a secrets manager, never in source control and never in frontend code. Use distinct variable names per environment so a misconfigured deploy fails loudly instead of silently pointing at production, and rotate them periodically — or immediately if exposure is suspected — a compromised secret must be revoked immediately.

Requesting a token​

curl --request POST \
  --url 'https://api.sdb.lbpay.com.br/v1/oauth2/token' \
  --header 'accept: application/json' \
  --header 'content-type: multipart/form-data' \
  --form client_id=YOUR_CLIENT_ID \
  --form grant_type=client_credentials \
  --form client_secret=YOUR_CLIENT_SECRET

Use the returned token as a Bearer credential:

curl --request GET \
  --url 'https://api.sdb.lbpay.com.br/v1/balance/realtime' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Token lifetime and renewal​

Tokens expire after 2 hours. Your integration must renew them automatically — never let a scheduled job fail because nobody refreshed a token by hand.

Two rules keep this reliable:

  • Refresh proactively, using a safety margin (renew when less than ~5 minutes remain) rather than waiting for the token to expire.
  • Cache the token in shared storage. A fleet of workers each minting its own token multiplies load on the auth endpoint for no benefit.

Handling 401 Unauthorized​

A 401 means the token is invalid or expired. The correct response is to renew the token and retry the request exactly once. If the retry also returns 401, the credentials themselves are wrong — stop and alert, do not loop.

Never log the full request

Request logs that include the token or client_secret turn your observability stack into a credential store. Log the request id, route and status code — not the headers or body of the auth call.

See Error handling for the complete HTTP status map.

Next step​

Run the Quickstart to make your first transaction end to end.