Getting started
Authentication
Every API request is authenticated with a Bearer token in the Authorization header.
API keys
Two kinds:
sk_test_...
Test mode. No real money moves. Sessions render with a Simulate button. 25 requests/sec limit.
sk_live_...
Live mode. Real payments. Requires completed KYC (Individual) or KYB (Business). 100 requests/sec limit.
Using your key
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxGenerating keys
Go to Dashboard → API keys → Issue new key. You'll see the key once — copy it immediately. Blockcade stores only a SHA-256 hash; if you lose the plaintext, revoke and re-issue.
Rotating keys
To rotate: issue a new key, roll it out to your servers, revoke the old one. Rotation is manual — automated rotation via key IDs is planned.
Security
- Never commit keys to source control. Use environment variables or a secrets manager.
- Never expose keys in client-side code. All Blockcade calls must be made server-side.
- Never share keys over email or chat. If a key is compromised, revoke immediately in Dashboard → API keys.
- Signup emails include your first test key. This is safe for initial exploration only.
Errors
| Status | error.type | Meaning |
|---|---|---|
| 401 | authentication_required | Missing or malformed Authorization header. |
| 401 | authentication_required | Key was revoked or belongs to a different account. |
| 403 | forbidden | Test key trying to hit a live-only endpoint (or vice versa). |
| 429 | rate_limited | Too many requests. See rate limits → |
Webhooks use a separate secret
Webhook signature verification uses your webhook signing secret, not your API key. Each webhook endpoint has its own secret. See Webhooks →