> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/api-v1/authentication.md).

# Authentication

API v1 can be called **with or without an API key**. Without one you're on the free tier and identify yourself with your public `integratorId`; with one you get higher rate limits, can charge an [integrator fee](https://docs.swapper.finance/api-v1/integrator-fees.md), and can create [deposit addresses](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md), which require a key.

## Your `integratorId`

Your `integratorId` is your public identity at Swapper — the same id you pass to the widget. It **identifies** you; it doesn't **authenticate** you: it ships in your frontend, so anyone can read it and send it. You'll find it in the [Integrator Dashboard](https://docs.swapper.finance/integrator-dashboard/overview.md) under **Settings**. To get one, sign up in the [dashboard](https://swapper.finance/dashboard/).

## Without a key (free tier)

Send your id as `integrator` — a field of the JSON body on `POST` endpoints, a query parameter on `GET` endpoints. It's **required on `/v1/quote`**:

```bash
curl -X POST "https://swapper.finance/api/v1/quote" \
  -H "Content-Type: application/json" \
  -d '{ "integrator": "YOUR_INTEGRATOR_ID", "fromChain": 8453, … }'
```

* An unknown or malformed `integrator` is rejected with `400` [`INVALID_INTEGRATOR`](https://docs.swapper.finance/api-v1/errors.md#error-codes).
* The catalog and status endpoints (`/v1/chains`, `/v1/tokens`, `/v1/token`, `/v1/status`) don't need it. You can still add `integrator` to any request so it's counted under your integrator on the dashboard's **API usage** page.
* Keyless requests are rate-limited per client IP, with a ceiling per `integratorId` — see [Rate Limits](https://docs.swapper.finance/api-v1/rate-limits.md).

## With an API key

### Create a key

Owners create keys in the [Integrator Dashboard](https://docs.swapper.finance/integrator-dashboard/overview.md#api-keys) under **API keys**:

* Keys look like `swp_` followed by 43 characters.
* **The full key is shown once**, when you create it. Copy it straight into your secret manager; afterwards the dashboard only shows its prefix (e.g. `swp_AbCd1234`).
* You can hold up to **10 active keys**. All keys of an integrator share one rate-limit budget.
* Keys are for **production** — there is no testnet environment for the API.

Name each key after where it lives ("Production server", "Reporting job") so you know what breaks if you revoke it.

### Send it

Send the key in the `x-swapper-api-key` header on every request:

```bash
curl -X POST "https://swapper.finance/api/v1/quote" \
  -H "x-swapper-api-key: $SWAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fromChain": 8453, … }'
```

* The key determines your integrator, so **omit `integrator`**. If you do send it, it must match the key's integrator, or the request fails with `400` `INVALID_INTEGRATOR`.
* An unknown or revoked key fails with `401` [`INVALID_API_KEY`](https://docs.swapper.finance/api-v1/errors.md#error-codes). v1 never silently downgrades a bad key to the free tier.

### What a key unlocks

* **Higher rate limits**, counted per integrator instead of per IP — see [Rate Limits](https://docs.swapper.finance/api-v1/rate-limits.md).
* **Integrator fees** — `fee` on `/v1/quote`. See [Integrator Fees](https://docs.swapper.finance/api-v1/integrator-fees.md).
* **Your own fee details on `/v1/status`** — for transfers that belong to you, the response also includes `integrator` and the `feeCosts` breakdown.
* **Per-key attribution** on the dashboard's API usage page.

{% hint style="warning" %}
**Keep API keys on your servers.** Never put a key in a browser bundle, a mobile app, or a repository — anyone who has it can use your rate-limit budget and act as your integrator. From a browser, call the API **without a key** and protect your `integratorId` with [allowed origins](#browser-requests-and-allowed-origins).
{% endhint %}

### Rotate and revoke

To rotate: create a new key, deploy it, then revoke the old one in the dashboard. A revoked key stops working within a minute — requests using it then fail with `401 INVALID_API_KEY`. Revoking can't be undone.

If a key leaks, revoke it immediately and create a replacement.

## Browser requests and allowed origins

Because your `integratorId` is public, someone else's site could send it. **Allowed origins** let you lock browser use of your id to your own sites. Owners set them in the dashboard under **Settings → Allowed origins**.

The list is **opt-in** — while it's empty, any site can use your id. Once you add at least one origin:

* **Keyless browser requests that name your `integratorId` from any other origin are rejected** with `403` [`ORIGIN_NOT_ALLOWED`](https://docs.swapper.finance/api-v1/errors.md#error-codes).
* **Requests from your listed origins get widget-level rate limits** — counted per end-user IP instead of against the shared public limits. See [Rate Limits](https://docs.swapper.finance/api-v1/rate-limits.md).

Not affected by the list:

* requests that carry an **API key**;
* **server-side** requests (no `Origin` header);
* Swapper's **hosted widget** (`https://deposit.swapper.finance`, what the [iframe SDK](https://docs.swapper.finance/widget-integration/iframe-sdk.md) loads) — it always works.

{% hint style="info" %}
If you embed the widget package (`@swapper-finance/deposit-sdk`) **directly** in your page instead of the hosted iframe, its requests come from your own site — add that origin to the list before you turn the restriction on.
{% endhint %}

Origins are written as `scheme://host[:port]` with no path, e.g. `https://app.example.com`. They must use `https` (`http` is only accepted for `localhost`); you can list up to 20. The browser's `Origin` header is matched (or the `Referer`'s origin when there is no `Origin`).
