Platform & Onboarding
Authentication and API Keys
Authenticate requests, issue scoped API keys, and separate test from live projects.
API keys
Every request carries an API key as a Bearer token.
Authorization: Bearer sk_live_...| Key | Project | Use |
|---|---|---|
sk_test_ | Test | Build and test. Available before verification. |
sk_live_ | Live | Real funds. Requires a verified business (KYB). |
A key is shown once, when it is issued. We store only a hash of it, so a lost key cannot be recovered; issue a new one and revoke the old.
Test and live
Each project is either test or live, and its keys match. Creating a live project, or calling with a live key, before your business is verified returns 403 kyb_required. See Verification and Team.
Scopes
Each key carries the scopes you grant it. Every endpoint in the API Reference states the scope it requires.
| Resource | Scopes |
|---|---|
| Customers | customers:read, customers:write |
| Wallets | wallets:read, wallets:create, wallets:write |
| Transactions | transactions:read, transactions:create |
| Quotes | quotes:read |
| Payment Links | payment_links:read, payment_links:write |
| Webhooks | webhooks:read, webhooks:write |
| Recoveries | recoveries:read, recoveries:create |
| Recovery contacts | recovery-contacts:read, recovery-contacts:write |
Scope by area
| Area | Read | Change |
|---|---|---|
| Wallets, passkeys, guardians | wallets:read | wallets:create (new wallets), wallets:write |
| Treasury and spend caps | wallets:read | wallets:write |
| Payments and approvals | transactions:read | transactions:create |
| Swaps and transfers | quotes:read (quotes) | transactions:create |
Acting for a customer
Requests about one customer's wallets carry the x-customer-id header, set to the id returned when you created the customer.
x-customer-id: <customer id>Errors
| Code | Status | Cause |
|---|---|---|
unauthorized | 401 | The Authorization header is missing or malformed, or the key is unknown or revoked. |
forbidden | 403 | The key lacks the scope the endpoint requires. |
kyb_required | 403 | A live project or live key was used before your business is verified. |
rate_limit_exceeded | 429 | The key exceeded its request budget for the window. |