> ## Documentation Index
> Fetch the complete documentation index at: https://docs.etherfuse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Authentication

> Authenticate requests with your Etherfuse API key: format, scope, and key management.

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.

```bash theme={null}
curl https://api.sand.etherfuse.com/organization/<organization_id>/payment_accounts \
  -H "Authorization: <your_api_key>"
```

<Warning>
  **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`.
</Warning>

## Key format

An Etherfuse API key has three colon-separated segments:

```
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 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](#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](/v2/overview#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.

| Environment | Base URL | Dashboard | Availability |
| - | - | - | - |
| **Sandbox** | `https://api.sand.etherfuse.com` | [sandbox.etherfuse.com](https://sandbox.etherfuse.com/account/manage) | After KYB, self-approved |
| **Production** | `https://api.etherfuse.com` | [app.etherfuse.com](https://app.etherfuse.com/account/manage) | After KYB approval |

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.

<Note>
  **Production keys require business verification (KYB).** You can't create production keys until your organization completes KYB at [app.etherfuse.com/compliance](https://app.etherfuse.com/compliance). Sandbox requires KYB too, but you can approve it yourself with the **Approve KYB** button on the [KYB page](https://sandbox.etherfuse.com/account/kyb).
</Note>

## Managing keys

<Note>
  **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](https://sandbox.etherfuse.com/account/manage) page to create a business organization and select it, then complete KYB. In sandbox, click **Approve KYB** at the bottom of the [KYB page](https://sandbox.etherfuse.com/account/kyb) and key management appears.
</Note>

Create and manage keys in the dashboard under **Account → Manage Accounts** ([sandbox](https://sandbox.etherfuse.com/account/manage) · [production](https://app.etherfuse.com/account/manage)):

* **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).

<Note>
  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.
</Note>

## 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](/v2/api-reference/lookup/list-stablebonds) for which endpoints are public.

To let a customer sign in with your own identity provider, see [JWT authentication](/v2/guides/jwt-authentication).

## 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_{env}:{key_id}:{org_id}` value | Use the complete key, all three segments |
| Can't see key management / prompted to finish KYB on sandbox | Viewing a **personal** account, or KYB not approved on the business account | Create/select a business org via **Add account**, then click **Approve KYB** on the KYB page |

v2 endpoints return a `401` as a problem details body with `type` ending in [`unauthorized`](/v2/errors#unauthorized). See [Errors](/v2/errors) for the other status codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.