API security best practices

How to protect your secret keys, webhooks and integration.

API security best practices

Never expose secret keys

  • sk_live_… and sk_test_… grant full merchant access. Never ship them in browser code, mobile apps, git repos, logs, error reports, or client-side analytics.
  • Always call the Southbill API from your server. From the browser, only ever use the client_secret returned by POST /v1/checkout/sessions.
  • Rotate keys immediately if you suspect a leak (Dashboard → Developers → Revoke).

Separate test and live

  • sk_test_… keys only work in test mode and never move real money. Use them for CI, staging and local development.
  • Live keys should be stored in your production secret store (AWS Secrets Manager, Vault, GitHub Actions Secrets, etc.) — never in .env files committed to git.

Enforce TLS

  • The API only accepts requests over HTTPS (TLS 1.2+). Plaintext HTTP is rejected.
  • Verify TLS certificates in your HTTP client. Disabling verification defeats the point.

Always use Idempotency-Keys

  • Send an Idempotency-Key header on every POST that creates money-moving objects.
  • Use a stable value per business action (e.g. order_12345) — not a random UUID per retry.
  • See Checkout Sessions → Idempotency.

Verify webhook signatures

  • Never trust a webhook body without verifying the Southbill-Signature header with your whsec_… secret.
  • Reject signatures older than 5 minutes (replay protection).
  • See Webhooks → Verify signatures.

Rate limits

  • Per API key, per minute: 120 Checkout Session creates, 300 reads, 60 writes (products, subscriptions, refunds).
  • Exceeding returns 429 rate_limited with a Retry-After header. Implement exponential backoff.

Principle of least privilege

  • Create separate keys per environment / service and revoke unused ones.
  • Keys are scoped — create one key per service with only the scopes it needs (checkout:write, refunds:write, products:write, …).

Incident response

If a key is leaked:

  1. Revoke it in the Dashboard immediately — all requests using it start returning 401.
  2. Create a new key and deploy it.
  3. Review the Developers → Request log for suspicious traffic.
  4. Contact support@southbill.com if funds were moved that you did not authorise.