> ## 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`.
</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 `/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) | Instant — any admin |
| **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 and uploads its business documents at [app.etherfuse.com/account/docs](https://app.etherfuse.com/account/docs). Sandbox keys are available immediately.
</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. 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](https://sandbox.etherfuse.com/account/manage) 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.
</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'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.
</Note>

## 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](/api-reference/lookup/list-stablebonds) 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 |

See the full [Errors](/errors) reference for other status codes.