API Authentication & Security

Handle uses Bearer Token Authentication over TLS 1.3 to authenticate all API requests.

Authorization: Bearer sk_live_...
Content-Type: application/json

API Key Types

Key Prefix	Environment	Purpose
`sk_live_...`	Production (Live)	Debits real bank accounts and executes real NIP merchant settlements.
`sk_test_...`	Sandbox (Test)	Simulates charges, pushes, and webhooks with zero real funds moved.

Secret keys are hashed using SHA-256 before being stored in the Handle database. Handle will never display your secret key again after initial generation. Keep it stored securely in your .env file or secret manager.

Request Idempotency (`X-Idempotency-Key`)

To prevent accidental double-billing if network connection drops during an API call, you can pass a unique X-Idempotency-Key header:

POST /v1/charges/dispatch
Authorization: Bearer sk_live_...
X-Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d

If you retry a request with the exact same idempotency key, Handle returns the saved original response instead of re-debiting the customer.

IP Whitelisting & Domain Security

For enterprise merchants, you can lock your API keys to specific production server IP addresses in the Handle Merchant Dashboard. Requests originating from unlisted IP addresses are rejected with 403 Forbidden.