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

# API keys and scopes

> What a key can do, and the one thing it deliberately cannot.

An API key is a `key_id` and a 32-byte secret. It is bound to your account, so
a key trades the same balance and the same positions you see in the browser —
there is no separate bot sub-account.

## Scopes

Every key carries a set of scopes. Scopes belong to the key, not to the request.

| Scope      | Grants                                                                             |
| ---------- | ---------------------------------------------------------------------------------- |
| `read`     | All `GET` endpoints: markets, orderbook, trades, balance, positions, fills, orders |
| `trade`    | Order mutations: place, cancel, batch, decrease, mass-cancel                       |
| `withdraw` | `POST /v1/withdrawals` only                                                        |

**Keys you create are `read+trade`.** They can do everything a trading bot
needs, and they intentionally cannot withdraw.

<Note>
  **Why bot keys cannot withdraw.**

  An API key is a long-lived secret. It lives in scripts, `.env` files, CI
  secrets and agent configs, which makes it the credential most likely to leak.
  If trading authority also meant withdrawal authority, a leaked key would mean
  irreversible loss of funds rather than merely unwanted trades.

  So `withdraw` is a separate scope and is never granted to a key you create.
  Withdrawals happen from the signed-in web wallet. A `POST /v1/withdrawals` with
  a bot key returns:

  ```json theme={null}
  { "error": { "code": "missing_scope", "origin": "gateway", "message": "missing scope" } }
  ```

  with HTTP `403`. This is enforced by the exchange, not by a proxy.
</Note>

## What a leaked key can still do

Being precise about the residual risk, because "cannot withdraw" is not "cannot
hurt you". Someone holding your key can:

* read your balance, positions, fills and order history
* place and cancel orders, and therefore lose your money through bad trades

Treat a key as you would a password. If you suspect exposure, revoke it.

## Revoking

`DELETE /keys/{key_id}` on the accounts service, or **Revoke** in
**Settings → API keys**. Revocation takes effect immediately and cannot be
undone; create a new key instead.

Revoking is idempotent, so it is safe to retry if you get an error.

## Limits

* No cap on how many keys you hold, and keys do not expire.
* Rate limits are per key. See [Rate limits](/concepts/rate-limits).
* Deleting your account revokes all of its keys.

## Key IDs

`key_id` is a small integer and is not a secret — it appears in every request
header. Only the secret authenticates you.