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:

Header
Authorization: Bearer $CLOBEPAY_API_KEY

X-API-Key: <key> is also accepted. If you send both headers with different values, the API returns 400 ambiguous_credentials.

cURL · Check your key
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.

Key scopes
ScopeResource
payment_links:read / :writePayment links
payins:readPayins
deposit_accounts:read / :writeDeposit accounts
payouts:read / :writePayouts, beneficiaries and wallets
balance:readBalance
verification:read / :writeKYC/KYB
webhooks:read / :writeWebhook 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

Authentication errors
HTTPCodeCause
401missing_credentialsNo key was sent.
401invalid_api_keyThe key does not exist or does not match.
401api_key_revokedThe key was revoked.
401api_key_expiredThe key expired (for example, after a rotation).
401api_key_wrong_environmentTest key in live, or the other way around.
403insufficient_scopeThe key lacks the scope for the operation.
403merchant_not_operationalThe 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 Authorization header.
  • One key per service and environment; rotate it if you suspect a leak.