> ## 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 are no OAuth flows or token exchanges — just your key.

```bash theme={null}
curl https://api.sand.etherfuse.com/ramp \
  -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>`. Sending a `Bearer` prefix is the most common cause of a `401 Unauthorized`.

## 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 `/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](#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](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 [etherfuse.com/start](https://etherfuse.com/start). KYB is simulated in sandbox; you approve it yourself with the **Approve KYB** button on the [KYB page](https://sandbox.etherfuse.com/start).

## 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/start) and key management appears.

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

> [!NOTE]
>
> 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](https://docs.etherfuse.com/api-reference/lookup/list-stablebonds.md) 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, or KYB not approved on the business account | Create/select a business org via **Add account**, then click **Approve KYB** on the KYB page |

See the full [Errors](https://docs.etherfuse.com/errors.md) reference for other status codes.


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