Skip to main content
The Etherfuse API authenticates every request with an API key sent in the Authorization header. There is no OAuth flow; you send the key itself.
Do not use a Bearer prefix. The header value is the raw API key: Authorization: <your_api_key>, not Authorization: Bearer <your_api_key>. A Bearer prefix is the most common cause of a 401 Unauthorized.

​
Key format

An Etherfuse API key has three colon-separated segments:

​
What a key can do

A single key grants full access to every v1 and v2 endpoint for its organization and for any child organizations you create under it. There are no per-key roles, scopes, or IP allowlists; a key grants all or nothing for its org. Public /lookup endpoints need no key. See Public endpoints. v2 payment account, quote and order routes take the organization they act for as {organizationId}. The key can act for its own organization and for its direct customer organizations; any other id returns 404 not-found. Webhook subscriptions and GET /orders belong to the organization that owns the key. See Organizations in the route. 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. The endpoints and auth scheme are identical across environments; only the base URL and key differ. Build against sandbox, then swap the base URL to go live.
Production keys require business verification (KYB). You can’t create production keys until your organization completes KYB at app.etherfuse.com/compliance. Sandbox requires KYB too, but you can approve it yourself with the Approve KYB button on the KYB page.

​
Managing keys

API keys require a business account. Keys are only available on business-type organizations; a personal account can’t create them. Use Add account on the Manage Accounts page to create a business organization and select it, then complete KYB. In sandbox, click Approve KYB at the bottom of the KYB page and key management appears.
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 is no grace period.
  • There is 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. Call the API from your backend.

​
Public endpoints

A few Lookup endpoints (exchange rates, stablebonds, token costs, country codes) are public and require no key. Every other v2 endpoint requires authentication. See the API Reference for which endpoints are public. To let a customer sign in with your own identity provider, see JWT authentication.

​
Troubleshooting

v2 endpoints return a 401 as a problem details body with type ending in unauthorized. See Errors for the other status codes.