Authentication

The credential of your machine is the pair client_id and client_secret. Exchange the two for an OAuth2 token (client_credentials) and send the token in Authorization: Bearer on every call to /v2/. The token is valid for 900 seconds.

The API only accepts calls from the IPs of your server registered on your credential. You generate the client_secret and enter the outbound IPs in the dashboard, in The secret and the IPs in the dashboard.

Token #

POST /oauth/token

The client_id and the client_secret go in HTTP Basic. That is what curl -u does:

curl -u "loja01:SEU_CLIENT_SECRET" -d "grant_type=client_credentials" -d "scope=cob.write cob.read pix.read ex.saldo.read ex.config.read" https://api.amunpay.com/oauth/token

POST /oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=cob.write cob.read pix.read ex.saldo.read ex.config.read
→ 200
{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IjAxSjEifQ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "cob.write cob.read pix.read ex.saldo.read ex.config.read"
}

As an alternative to Basic, client_id and client_secret may go in the form body. Sending both in both forms with different values responds 400 invalid_request.

The token is only issued for, and only valid on, calls coming from the registered IPs: from another IP, the token request and every call respond 403 origem_nao_permitida. With no IP registered, no call goes through.

The secret and the IPs in the dashboard #

The manager of your company generates the client_secret in the dashboard, under Integration, in the Credentials tab, with the second factor code. The secret appears once, next to the client_id, each with a copy button, and is never shown again. If you lose it, generate another one: the previous one stops working immediately. Tokens already issued remain valid until they expire, except when you flag a suspected leak, which revokes them too.

The dashboard accepts a public IP, with a prefix up to /24 (IPv4) or /48 (IPv6), up to 20 IPs. Every action on the credential is emailed to the contacts of your company, without the secret. With no technical or financial contact registered, the dashboard neither generates the secret nor adds an IP.

Only the manager generates the secret and changes the IPs. The other users see the client_id and the IPs. If AmunPay turns on the second-factor wait for your account, a manager who has just enabled the second factor, who was promoted or reactivated, or whose password was reset by someone else, waits 24 hours to generate it. The credential of a sub-account with its own credential is generated by the holder company.

If the screen says the feature is not enabled for your account, talk to AmunPay. AmunPay can also generate the secret and register the IPs for you, and through AmunPay a new IP takes effect immediately.

First call #

GET /v2/ex/config

GET /v2/ex/config
→ 200
{
  "conta": { "status": "ATIVA", "desde": "2026-09-18T09:20:23Z" },
  "capacidades": {
    "pix": true,
    "subcontas": true,
    "split": true,
    "baas": false
  },
  "recebedor": { "chave": "01J8Z3QK5W7R2N4M6P8T0V2X4Y" },
  "custodia": { "tipo": "PROPRIA", "custodiante": "Conta PI", "recusaAntesDoCredito": true },
  "depositoPorChave": { "modo": "RECUSAR" }
}

Scopes #

Token errors #

POST /oauth/token responds in the format { "error", "error_description" }.

Errors on calls #