Authorization header. There are no OAuth flows or token exchanges — just your key.
Key format
An Etherfuse API key has three colon-separated segments:| Segment | Meaning |
|---|---|
api_ | Marks the value as an API key. |
{env} | sand (sandbox) or prod (production). The environment is baked into the key, so sandbox and production keys are not interchangeable. |
{key_id} | A random identifier unique to this key. |
{org_id} | Your organization’s ID — the key is scoped to this org. |
What a key can do
A single key grants full access to every/ramp endpoint for its organization — and to any child organizations you create under it. There are no per-key roles, scopes, or IP allowlists; a key is all-or-nothing for its org. (Public /lookup endpoints need no key — see Public endpoints.)
Keys are hashed server-side with an organization-specific salt, so a key only works for the org that issued it and can’t be reused elsewhere.
Sandbox vs. production keys
Use the key that matches the base URL you’re calling.| Environment | Base URL | Dashboard | Availability |
|---|---|---|---|
| Sandbox | https://api.sand.etherfuse.com | sandbox.etherfuse.com | Instant — any admin |
| Production | https://api.etherfuse.com | app.etherfuse.com | After KYB approval |
Production keys require business verification (KYB). You can’t create production keys until your organization completes KYB and uploads its business documents at app.etherfuse.com/account/docs. Sandbox keys are available immediately.
Managing keys
API keys require a business account. Keys are only available on business-type organizations — a personal account can’t create them. If “Manage Accounts” keeps prompting you to finish KYB (even on sandbox, where KYB isn’t required), you’re most likely viewing a personal account. Use Add account on the Manage Accounts page to create a business organization, make sure it’s the selected account, and key management will appear. On sandbox you can skip KYB with the bypass button; production keys still require KYB approval.
- Up to 5 active keys per organization.
- A new key is shown in full only once — copy it immediately and store it securely. Afterward the dashboard shows only the key’s first 16 characters for reference.
- Deleting a key revokes it immediately — there’s no grace period.
- There’s no in-place rotation. To rotate, create a new key, switch your integration over, then delete the old one — both work during the cutover (within the 5-key limit).
Treat API keys like passwords — store them in a secrets manager or environment variable, never in source control or client-side code. All calls should originate from your backend.
Public endpoints
A fewLookup endpoints (exchange rates, stablebonds, bond costs, country codes) are public and require no key. Everything under /ramp requires authentication. See the API Reference for which endpoints are public.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
401 Unauthorized | Bearer prefix on the header | Send the raw key: Authorization: <key> |
401 Unauthorized | Wrong-environment key | Match the key to the base URL (sandbox key ↔ sandbox URL) |
401 Unauthorized | Revoked, deleted, or mistyped key | Re-create the key in the dashboard |
401 Unauthorized (“invalid API key format”) | Sent something other than the full api_…:…:… value | Use the complete key, all three segments |
| Can’t see key management / prompted to finish KYB on sandbox | Viewing a personal account — keys need a business account | Create/select a business org via Add account; on sandbox use the KYB bypass button |