Authentication & API keys
Every API request is authenticated with a secret API key sent as a Bearer token. The key identifies your merchant account and decides whether the request runs in test or live mode.
Creating a key
- Sign in and open Developers → API keys.
- Choose Test or Live. Live keys are only available after your business verification is approved.
- Pick the permissions (scopes) the key needs, and optionally restrict it to your server IP addresses.
- Copy the secret. It starts with
sk_test_orsk_live_and is shown only once. We store only a hash of it and cannot show it again.
Sending the key
curl https://gatway.hunario.com/api/v1/balance \ -H "Authorization: Bearer sk_test_..."
Keys belong on your server only. Never put a secret key in browser JavaScript, a mobile app, or a public repository.
Scopes
Each key carries a set of permissions. A request to an endpoint the key is not allowed to use fails with 403 insufficient_scope.
| Scope | Allows |
|---|---|
payments:write | POST /payments, POST /payments/{id}/verify |
payments:read | GET /payments, GET /payments/{id}, GET /transactions |
payouts:write | POST /payouts, POST /payouts/{id}/cancel |
payouts:read | GET /payouts, GET /payouts/{id} |
balance:read | GET /balance |
| any valid key | GET /fees, GET /fees/quote, GET /currencies |
Give each integration only the scopes it uses. For example, a checkout server that only takes payments does not need payouts:write.
IP allowlist
When a key has an IP allowlist, requests from any other address are rejected with 403 ip_not_allowed. We recommend an allowlist for every live key that can request payouts.
Rotation and revocation
- Rotate issues a new secret with the same settings and revokes the old one. Deploy the new secret before you rotate, or expect requests with the old secret to fail.
- Revoke disables a key immediately. Revoked or expired keys return
401 invalid_api_key. - The dashboard shows when and from which IP each key was last used, which helps you find unused keys.
Authentication errors
| Status | Code | Meaning |
|---|---|---|
| 401 | authentication_required | No Authorization: Bearer header was sent. |
| 401 | invalid_api_key | The key is wrong, expired or revoked. |
| 403 | ip_not_allowed | The request came from an IP that is not on the key's allowlist. |
| 403 | insufficient_scope | The key lacks the scope named in details.required_scope. |
| 403 | account_suspended | Your merchant account is suspended. Contact support. |