The Etherfuse API authenticates every request with an API key sent in the Authorization header. There are no OAuth flows or token exchanges — just your key.
curl https://api.sand.etherfuse.com/ramp \
-H "Authorization: <your_api_key>"
Do not use a Bearer prefix. The header value is the raw API key — Authorization: <your_api_key>, not Authorization: Bearer <your_api_key>. Sending a Bearer prefix is the most common cause of a 401 Unauthorized.
api_{env}:{key_id}:{org_id}
| 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
Create and manage keys in the dashboard under Account → Manage Accounts (sandbox · production):
- 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 few Lookup 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 |
