API keys and authentication
Secret keys per merchant (MID) in Authorization: Bearer, scopes, rotation and revocation.
The public API authenticates with a secret key per merchant (MID). The MID comes from the key, so it is not part of the URL. Send the key on every request, always over HTTPS:
Authorization: Bearer $CLOBEPAY_API_KEYX-API-Key: <key> is also accepted. If you send both headers with different values, the API returns 400 ambiguous_credentials.
curl "$CLOBEPAY_API_BASE/me" \
-H "Authorization: Bearer $CLOBEPAY_API_KEY"Expected response: HTTP 200
Format
sk_<environment>_<key_id>.<secret>, where the environment is test or live. The full key is shown only once when created; afterwards you only see the prefix, the last 4 characters and its metadata (label, scopes, last use).
Scopes
Each key has per-resource permissions. A key created without explicit scopes has all of them except payouts:write: to create payouts via API you must include it when creating the key. Without the required scope the API returns 403 insufficient_scope.
| Scope | Resource |
|---|---|
payment_links:read / :write | Payment links |
payins:read | Payins |
deposit_accounts:read / :write | Deposit accounts |
payouts:read / :write | Payouts, beneficiaries and wallets |
balance:read | Balance |
verification:read / :write | KYC/KYB |
webhooks:read / :write | Webhook endpoints and deliveries |
Create, rotate and revoke
- The merchant owner creates them in the dashboard. The merchant must be operational.
- Up to 5 active keys per MID and environment.
- Zero-downtime rotation: create a new key, deploy it and schedule the previous key to expire (up to 168 hours) or revoke it.
- Revocation takes effect immediately.
Rate limits
Initial values per key: bursts of 50 requests per second and 1,000 per minute; creating payouts, 10 per minute. When exceeded the API returns 429 with Retry-After and the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
Authentication errors
| HTTP | Code | Cause |
|---|---|---|
| 401 | missing_credentials | No key was sent. |
| 401 | invalid_api_key | The key does not exist or does not match. |
| 401 | api_key_revoked | The key was revoked. |
| 401 | api_key_expired | The key expired (for example, after a rotation). |
| 401 | api_key_wrong_environment | Test key in live, or the other way around. |
| 403 | insufficient_scope | The key lacks the scope for the operation. |
| 403 | merchant_not_operational | The merchant is not operational. |
A resource that belongs to another merchant returns 404, not 403, so its existence is not disclosed.
Best practices
- Keep the key on the server only (environment variables or a secrets manager).
- Never put it in browser code, mobile apps or repositories.
- Do not log the
Authorizationheader. - One key per service and environment; rotate it if you suspect a leak.