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

# AI Spend Keys

> Use Lava as a drop-in API key for AI tools and agents with built-in budget controls

export const providerCountLabel = "185+";

A spend key is a single API key that works across {providerCountLabel} AI models through Lava. You set spending limits, choose which models are allowed, and Lava handles the rest. No need to sign up for separate provider accounts or manage multiple API keys.

## How It Works

1. You create a spend key in the Lava dashboard (or via REST API).
2. You paste the key into your AI tool as the API key, and point it at `https://api.lava.so`.
3. Lava routes your requests to the right provider, tracks usage, and enforces the limits you set.

Every request shows up in your **AI Spend** dashboard with cost, model, and token breakdowns.

## Key Types

| Key        | Prefix                      | Purpose                                         |
| ---------- | --------------------------- | ----------------------------------------------- |
| Spend key  | `lava_sk_`                  | Goes into your AI tool to make model requests   |
| Secret key | `aks_live_*` / `aks_test_*` | Used to manage spend keys from code or terminal |

<Note>
  Your spend key (`lava_sk_*`) is shown once when you create it. Copy it immediately. If you lose it, you can rotate the key from the dashboard to generate a new one.
</Note>

## Creating a Spend Key

### From the Dashboard

1. Open **Dashboard > AI Spend**.
2. Click **Create Spend Key**.
3. Fill in the details:
   * **Name** for your own reference (e.g. "Claude Code", "Production Agent")
   * **API format**: OpenAI (`/v1/chat/completions`) or Anthropic (`/v1/messages`), depending on your tool
   * **Model access**: allow all models, or restrict to specific ones
   * **Spend limit** (optional): set a cap per day, week, month, or total
4. Click **Create** and copy the full `lava_sk_*` key.

### From the Command Line

If you prefer working in a terminal, you can manage spend keys through the REST API. First, grab your secret key from **Dashboard > Gateway > Secrets**.

```bash theme={null}
export LAVA_SECRET_KEY="aks_live_your_key_here"
```

**Create a key:**

```bash theme={null}
curl -X POST "https://api.lava.so/v1/manage/spend_keys" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CLI Test Opus",
    "allowed_models": ["claude-opus-4-6"],
    "allowed_providers": ["anthropic"],
    "spend_limit": { "amount": "100.00", "cycle": "monthly" },
    "status": "active"
  }'
```

The response includes the full `key` (shown once), `spend_key_id`, and `key_preview`.

**List keys:**

```bash theme={null}
curl "https://api.lava.so/v1/manage/spend_keys?limit=20" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"
```

**Pause a key:**

```bash theme={null}
curl -X PUT "https://api.lava.so/v1/manage/spend_keys/sk_your_id" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'
```

**Revoke a key:**

```bash theme={null}
curl -X DELETE "https://api.lava.so/v1/manage/spend_keys/sk_your_id" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"
```

**Rotate a key** (generate a new secret without changing limits or usage history):

```bash theme={null}
curl -X POST "https://api.lava.so/v1/spend_keys/sk_your_id/rotate" \
  -H "Authorization: Bearer $LAVA_SECRET_KEY"
```

See the [API Reference](/api-reference/spend-keys/create-spend-key) for full request/response details.

## Managing Keys

From the **AI Spend** dashboard you can:

* **Pause or resume** a key without revoking it
* **Edit** the name, spend limit, or model restrictions
* **Rotate** the secret if you think it was exposed (your limits and usage history stay the same)
* **Revoke** a key permanently
* **View usage** per key, including current cycle spend, total spend, and last used timestamp

You can create up to 10 spend keys per wallet.

## Tool Setup Guides

We have step-by-step guides for connecting Lava to 9 popular AI tools, including Cursor, Claude Code, Vercel AI SDK, Raycast, LangChain, and more.

<Card title="Tool Setup Guides" icon="plug" href="/guides/spend-key-setup-guides">
  Connect your spend key to Cursor, Claude Code, Vercel AI SDK, Anthropic SDK, Raycast, OpenClaw, LangChain, Cline, and Codex CLI
</Card>

## Troubleshooting

### "Invalid API key" or 401 errors

* Make sure you're using the full `lava_sk_*` key, not the preview ending in `****`.
* Check that the key is **active**, not paused or revoked. You can see this on the AI Spend dashboard.
* If you lost the original key, rotate it from the dashboard to get a new one.

### "Model not allowed" errors

* Your key may have model restrictions. Check the allowed models on the key card in the dashboard, and make sure the model you're requesting matches one of them.

### Spend limit reached

* If your key has a spend limit and you've hit it, requests will be rejected until the next cycle resets (or you raise the limit).
* You can edit the spend limit from the dashboard or REST API without revoking the key.

### Wrong API format

* If you're getting unexpected errors, double-check that the API format on your spend key matches what your tool expects. Claude Code and the Anthropic SDK need **Anthropic** format. Most other tools need **OpenAI** format.

### Base URL issues

* Anthropic-format tools: use `https://api.lava.so` (without `/v1`), because the Anthropic SDK appends `/v1/messages` automatically.
* OpenAI-format tools: use `https://api.lava.so/v1`, because the OpenAI SDK appends `/chat/completions`.

## FAQ

**Do I need to pass a `wallet_id`?**

No. When you authenticate with your secret key, Lava automatically resolves your wallet. Most users only have one wallet.

**Can I use both the dashboard and the REST API?**

Yes. They manage the same underlying spend keys. Create a key in the dashboard, update it from the CLI, or vice versa.

**What's the difference between spend keys and forward tokens?**

Spend keys (`lava_sk_*`) are for your own AI tools and agents. Forward tokens are for the [gateway proxy flow](/gateway/forward-proxy) where you're billing your customers. They serve different purposes and work independently.

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/spend-keys/create-spend-key">
    Full REST API docs for creating, listing, updating, and revoking spend keys
  </Card>

  <Card title="Gateway Quickstart" icon="rocket" href="/get-started/quickstart-track">
    Route your first AI request through Lava in under 5 minutes
  </Card>
</CardGroup>