Authentication

Authenticate your requests securely with OAuth 2.0

Overview

The Conta Simples API uses OAuth 2.0 Client Credentials for authentication. This flow is suited for server-to-server calls without an end user.

Send a POST to the token endpoint. Send credentials (API key and API secret from Internet Banking) in the Authorization header as Basic: base64-encode API_KEY:API_SECRET and use that as the header value.

# BASIC_BASE64 = base64("YOUR_API_KEY:YOUR_API_SECRET")
curl --location 'https://api-sandbox.contasimples.com/oauth/v1/access-token' \
  --header "Authorization: Basic ${BASIC_BASE64}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "User-Agent: {your-app-name}/{version}" \
  --data "grant_type=client_credentials"

For production, use the base URL https://api.contasimples.com.

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Field	Description
`access_token`	JWT used to authenticate API calls
`token_type`	Always `Bearer`
`expires_in`	Token lifetime in seconds

Using the token

Include the token on every request in the Authorization header:

curl -X GET https://api-sandbox.contasimples.com/resource \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: {your-app-name}/{version}"

Never expose tokens in URLs, logs, or client-side code. Treat tokens as sensitive credentials.

Expiration and refresh

Token lifetime

Token issued

Valid for expires_in seconds (default: 1800 = 30 minutes).

Token about to expire

Refresh before expiry to avoid failed calls.

Token expired

Requests return 401 Unauthorized. Request a new token.

Refresh best practices

Refresh when about 10% of the lifetime remains. For a 30-minute token, refresh after about 27 minutes.

// Conceptual example
if (tokenAge > expiresIn * 0.9) {
  await refreshToken();
}

Cache the token (Redis, in-memory) to avoid unnecessary token requests.

If you get a 401 response, clear the cache, get a new token, and retry the original request.

Required headers

Every authenticated request should include:

Header	Value	Description
`Authorization`	`Bearer {TOKEN}`	OAuth 2.0 access token
`Content-Type`	`application/json`	Request body format

Security

Storing credentials

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
GCP Secret Manager
Environment variables at runtime (not committed to source code)

If credentials are compromised

Immediately open the credentials panel in Internet Banking and revoke the affected credentials
Generate new credentials in the same panel
Replace them across all environments
Check logs for unauthorized access
If needed, contact support

Troubleshooting

Common causes:

Token expired
Malformed token
Missing or wrong Authorization header

Fix: Get a new token and verify the header format.

Common causes:

Credentials not authorized for the environment

Fix: Verify your credentials.

Common causes:

Wrong grant_type
Invalid API key or API secret in Authorization: Basic
Malformed base64 (must be API_KEY:API_SECRET then encoded)

Fix: Verify the Authorization: Basic header and your base64 encoding.

Next steps

Environments

Sandbox vs Production.

Integration flow

What to do after authentication is set up.

Was this page helpful?

Last updated today

Built with Documentation.AI