API keys
Choose permissions, store keys securely, and replace or revoke server credentials.
An API key authorizes your server to act for one merchant in either live or test. Create and revoke keys in the merchant dashboard under Developers → API keys. API keys cannot create other keys or configure webhooks.
Key format and storage#
Keys start with sk_live_ or sk_test_, followed by 64 hexadecimal characters. Copy the secret when it is created and store it in your secret manager. Ordinary key lists show a prefix, not the full secret; there is no general secret-recovery operation.
A key's environment and permissions are fixed at creation. To change permissions, create a replacement key and revoke the old one.
Permissions by operation#
| Permission | Operations |
|---|---|
invoices:write | Create invoice |
invoices:read | Get and list invoices |
addresses:write | Create payment address |
addresses:read | Get and list payment addresses |
payouts:write | Create payouts |
payouts:read | Get and list payouts |
refunds:write | Create refund |
refunds:read | Get and list refunds |
balances:read | List balances; get and list conversions |
balances:manage | Create conversion; includes balances:read |
catalog:read (implicit) | Read currencies and rates; included for every authenticated key |
Read and write are independent, except that balances:manage also covers balances:read. Grant only the permissions the integration uses. For example, a checkout server needs invoice read/write; a reconciliation service can use read permissions without payout write access.
Replace a key#
- Create a new key for the same environment with the permissions your integration needs.
- Save the new secret and deploy it to your servers.
- Verify successful requests from every server and background worker that used the old key.
- Revoke the old key after the migration is complete.
Multiple keys may be active during this procedure. There is no merchant API operation that atomically rotates a key with a scheduled grace period, and keys do not expire on their own. Do not assume a key-expiry selector or automatic renewal is available.
The dashboard shows when each key was last used. That timestamp is approximate telemetry: it is refreshed at most once every five minutes, so a key used seconds ago can still read Never. Use it as a hint when retiring a key, and confirm against your own request logs before revoking.
Revoke a key#
Revoke a lost or exposed key in Developers → API keys: open the key and choose Revoke key. Revocation makes subsequent authentication fail; it does not cancel an invoice, payout, or refund that was already accepted. Replace the credential used by legitimate servers and investigate unexpected operations separately.
IP restrictions#
See IP access before configuring a non-empty allowlist. Source-IP restrictions are not ready to recommend for hosted integrations. Do not add platform or proxy addresses to work around a rejected request.