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

# API keys

> Create, rotate, and revoke the SDK keys that authenticate your requests.

Every swap request is authenticated with an **integrator API key**. You create and manage keys from your OneSwap account (self-serve), then pass the key to the SDK.

| Network | Create keys at                                 |
| ------- | ---------------------------------------------- |
| Mainnet | [swap.oneswap.cc](https://swap.oneswap.cc)     |
| Devnet  | [devnet.oneswap.cc](https://devnet.oneswap.cc) |

## Key format

A key looks like `sk_live_` followed by **48 hex characters**:

```
sk_live_0a1b2c3d…4e5f6071   # sk_live_ + 48 hex chars (shown once, at creation)
```

<Warning>
  The plaintext key is shown **once**, at creation. OneSwap stores only a hash of it, so it
  cannot be shown again. If you lose a key, mint a new one and revoke the old.
</Warning>

## How the SDK uses the key

Pass the key when you construct the client. The SDK sends it on every request as the HTTP header `x-sdk-key`:

```typescript theme={null}
import { OneSwap } from '@oneswap/sdk'

const oneswap = new OneSwap({ apiKey: 'sk_live_...' })
```

## Creating a key

Sign in to your OneSwap account — [swap.oneswap.cc](https://swap.oneswap.cc) for mainnet,
[devnet.oneswap.cc](https://devnet.oneswap.cc) for devnet — and open the **SDK keys**
section. Create a key with an optional label (e.g. "production backend"). The response shows
the plaintext `sk_live_...` value **once** — copy it into your server's secret store
immediately.

## Listing keys

The same account page lists your keys — label, active state, rate limit, and creation date.
The secret is never shown again; only metadata is listed.

## Rotating a key

There is no in-place rotation. To rotate:

1. Create a new key from your account.
2. Deploy it to your servers.
3. Revoke the old key once nothing uses it.

## Revoking a key

Revoke (delete) a key from the same account page. This is how you rotate out a leaked or
retired key — revocation is immediate.

## Rate limits

Each key has a base per-minute rate limit (`ratePerMin`), and operations are tiered relative to it:

| Operation                                     | Limit                                                 |
| --------------------------------------------- | ----------------------------------------------------- |
| `swaps.createSwap`                            | The tightest tier — **1×** the key's per-minute limit |
| `swaps.getSwap` / `swaps.waitForSwap` polling | **4×** the create rate                                |
| `quotes.get`, `pools.*`, `tokens.list`        | Generous read ceilings, shared with anonymous traffic |

On top of the base limit, OneSwap can configure **per-operation limits for your key**
(different ceilings for creating swaps, quoting, reading tickers, and so on). If your
integration needs more headroom on a specific operation — say, high-frequency quoting —
ask for a per-operation raise rather than a blanket one.

Exceeding a limit returns HTTP `429` (`RateLimitError`). Back off and retry — see
[Error handling](/guides/error-handling).

## Security best practices

<Warning>
  Treat your `sk_live_` key like a password. Anyone with it can create swaps under your
  integrator account.
</Warning>

* **Server-side only.** Keep the key on your backend. Never ship it to a browser, mobile app, or any end-user surface.
* **Never expose it to end-users.** Your users interact with a deposit party — they never need, and must never see, your key.
* **Store it in a secret manager**, not in source control or client bundles.
* **Use separate keys** per environment or service so you can revoke one without disrupting the others.
* **Revoke immediately** if a key is exposed, then create a replacement.