Register the public key
In the portal, signed in as an account administrator: Integrations → New API credential.
| Field | What it is |
|---|---|
| Name | Identifies the integration on your screen. Grants no access. |
| Profile | read_only: statements, queries and charge lookups. full_access: moves funds |
| Allowed IPs | Required. Individual IPv4 addresses (203.0.113.10), at least one. A credential with no source restriction is not issued. See Fixing your IPs. |
| Public key | Upload of publicKey.pem (≤ 4 KB), or the Generate keys button |
You receive a client_id and a kid. Neither is secret, so you can look them up again whenever
you want.
About the IP list
Individual IPv4 addresses only. Ranges and IPv6 are not accepted, and the source IP is checked on every request, against the address of the peer that reaches us. If you call through a proxy of your own, register the addresses your proxy exits from, not your application's.
Fixing your IPs covers how to give your workload a fixed egress address on each cloud provider, and how to find the one you actually leave from.
Profiles
A profile is a fixed set of capabilities. It is signed into the credential, so the route you can call is decided by what the account administrator approved, not by anything sent at runtime.
| Profile | Can | Cannot |
|---|---|---|
read_only | read balances, statements, charges, locations, PIX records and webhooks | write anything |
full_access | everything read_only can, plus create charges, move funds, refund and transfer |
Ask the portal for the live list rather than hardcoding it. Profiles are versioned
(read_only@1), and a new version may appear.
One credential = one key, one account, one profile
There is no "edit the key". To rotate a key you create a new credential in the same integration, migrate your application to it, and revoke the old one. Two credentials can be valid at the same time during the rotation window, which is what makes a zero-downtime rotation possible:
Profile and allowed IPs can be edited: the portal replaces the credential with a new signed
version that keeps the same key and client_id. Your application does not change; the previous
version stops being accepted.
Revocation
Revoking is irreversible and takes effect in about a second. There is no "unrevoke": if you revoked by mistake, create a new credential.
Creation and revocation of every credential are recorded in an immutable, append-only log.