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.

Getting a token

Request

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

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

Next steps

Environments

Sandbox vs Production.

Integration flow

What to do after authentication is set up.

Was this page helpful?