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

# Authentication

> API keys, scopes, spending limits and rate limits.

Every `/v1` call except the OpenAPI document needs an API key:

```bash theme={"dark"}
curl -sS "$LEAN_API_URL/v1/markets" -H "Authorization: Bearer $LEAN_API_KEY"
```

## Create a key

Each key belongs to one trading account and has its own limits. A key is either a test key
(`lean_sk_test_…`) or a live key (`lean_sk_live_…`). Both use the same trading account. Test keys
simulate orders and fills with no money; live keys trade real money, and trading can be paused
platform wide. A key's mode is set when you create it and can't be changed. See
[Test mode and live mode](https://docs.lean.xyz/test-mode.md).

1. Sign in to Lean.
2. Open Settings (the gear) and choose **API**.
3. Under **API keys**, choose **Create API key**. Give the key a name, then choose its mode, access,
   per order limit, daily limit and expiry. The mode is **Test** and the access is **Read and trade**
   unless you change them. Choose **Create key**.
4. Under **Copy your key now**, choose **Copy**, then **Done**. You won't see the key again.

> [!WARNING]
>
> Lean stores only a hash of the key and cannot recover a lost one. Keep it in a secret manager,
> never in source control.

| Setting | Meaning |
| - | - |
| Access | **Read only** allows every `GET`, `POST /v1/orders/preview`, `POST /v1/transfers/quote` and `POST /v1/ws/token` (a stream ticket): markets, quotes, previews, balances, positions, orders and streams. **Read and trade** also allows placing, amending and canceling orders, stop losses, limit chases and transfers, and paying for a buy with cash on the other venue, between Polymarket and Hyperliquid. In the API, **Read only** is the `read` scope and **Read and trade** is `read`, `trade` and `route`. A **Read and trade** key made before one-call routing shipped (see the [changelog](https://docs.lean.xyz/changelog.md)) has only `read` and `trade`: create a new key to pay from the other venue. |
| Per order limit | The largest single order, in USD. Lean refuses any order above it before it reaches a venue. |
| Daily limit | The total notional, in USD, the key may place in any rolling 24 hours. Stop losses, limit chases and transfers count toward it too. A canceled, rejected or expired order counts only the part that filled. It must be at least the per order limit. |
| Allow withdrawals | Off unless you turn it on. Lets the key withdraw through the API, with an optional per withdrawal limit and daily withdrawal limit, in USD. See [Withdrawals through the API](https://docs.lean.xyz/funding.md#withdrawals-through-the-api). |
| Expiry | From 1 to 90 days. The default is 90. |

The **API keys** list shows each key's name with a **Test** or **Live** badge, its prefix (such as
`lean_sk_test_xxxxxxxx…`), when it was created, last used and expires, and whether it is Active,
Revoked or Expired. A user can hold up to 10 active keys; revoke one to create another.

### Manage keys with the API (advanced)

If you manage keys from your own tooling, call `/api-keys` instead. These requests take the access
token of your Lean session while you are signed in, sent as `Authorization: Bearer <token>`, never an API key. The
token expires after a short time.

> [!WARNING]
>
> A session token acts as you, signed in. Use it only to create, list and revoke keys, never paste
> it into a program, and don't share it.

```bash theme={"dark"}
curl -sS -X POST "$LEAN_API_URL/api-keys" \
  -H "Authorization: Bearer $LEAN_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-bot",
    "mode": "test",
    "tradingAccountId": "<your trading account id>",
    "scopes": ["read", "trade", "route"],
    "maxOrderNotionalMicros": 5000000,
    "dailyNotionalLimitMicros": 25000000,
    "expiresInDays": 7
  }'
```

Send the body as JSON with `Content-Type: application/json`, or the request is refused with
`400 VALIDATION_ERROR`. The secret is in `data.secret`. `mode` is `test` or `live` and defaults to `test`. `scopes` takes
`read`, `trade` and `route`. `route` lets the key pay for a buy with cash on the other venue (see
[Paying from the other venue](https://docs.lean.xyz/orders.md#paying-from-the-other-venue)) and needs `trade`. Leave it out for a key that should only trade with the cash already on each venue. A key can
also take `withdraw`, with optional withdrawal limits; see
[Withdrawals through the API](https://docs.lean.xyz/funding.md#withdrawals-through-the-api). Limits are in millionths of a dollar, so `5000000` is \$5. The API
reference documents [Create an API key](https://docs.lean.xyz/api-reference/api-keys/create-api-key.md),
[List API keys](https://docs.lean.xyz/api-reference/api-keys/list-api-keys.md) and
[Revoke an API key](https://docs.lean.xyz/api-reference/api-keys/revoke-api-key.md), with every field and error.

## Rotate and revoke

To rotate a key, create a new one, move your client to it, then revoke the old one: in Settings,
**API**, choose **Revoke** on its row, then **Revoke** again to confirm. Programs using the key stop
working immediately, and this can't be undone. With the API:

```bash theme={"dark"}
curl -sS -X DELETE "$LEAN_API_URL/api-keys/<key id>" \
  -H "Authorization: Bearer $LEAN_SESSION_TOKEN"
```

Lean refuses revoked and expired keys immediately.

## Failures

| HTTP | `code` | Cause |
| - | - | - |
| 401 | `UNAUTHORIZED` | No key, a malformed key, or an unknown, expired or revoked key. |
| 403 | `FORBIDDEN` | The key lacks the scope, or its account has no API access. |
| 429 | `RATE_LIMITED` | More than 5 requests a second per key, with bursts up to 20. Cancels have their own budget of 10 a second, with bursts up to 40. Wait for the `Retry-After` header. |
| 503 | `INTERNAL_ERROR` | Lean could not check the key's rate limit, so it did not serve the request. Retry later. |


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