> ## 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.

# Manage AI Spend & API Keys

> Create scoped API keys with spend limits for agents and developer tools

Spend keys are scoped API keys that work as drop-in replacements for provider API keys. Use them to give agents, team members, or developer tools access to AI models with built-in spend limits, model restrictions, and rate controls.

> [!NOTE]
>
> **Start here:** [Authenticate an Agent](https://lava.so/docs/agents/authenticate.md) explains when to use MCP session auth versus the SDK login flow.

## MCP flow

The Lava MCP server auto-manages a spend key for gateway access. When you call `login`, a spend key is provisioned automatically for the MCP session.

* `login` to authenticate — auto-provisions a spend key for `prompt` and `call` access
* `prompt` or `call` to route traffic, spending against the auto-provisioned key
* `search` to discover available providers before routing

To create spend keys with custom limits, model restrictions, or expiration — use the SDK code below.

## SDK flow

If you are writing code directly, use the examples below with `@lavapayments/nodejs`.

## How Spend Keys Work

A spend key is an OpenAI-compatible API key that routes through Lava's gateway. Any tool that accepts an OpenAI API key can use a Lava spend key instead. You control which models are allowed, how much can be spent, and how fast requests can be made.

## Create a Spend Key

> [!NOTE]
>
> Creating and rotating spend keys is enabled on request. Until your account is enabled, `POST /v1/spend_keys` and `POST /v1/spend_keys/{id}/rotate` return `403 spend_key_issuance_paused`. Email [support@lava.so](mailto:support@lava.so) to request access. Existing spend keys continue to work.

```typescript theme={null}
import { Lava } from '@lavapayments/nodejs';

const lava = new Lava(process.env.LAVA_SECRET_KEY);

const spendKey = await lava.spendKeys.create({
  name: 'Agent - Production',
  allowed_providers: ['openai', 'anthropic'],
  allowed_models: ['gpt-4o-mini', 'claude-sonnet-4-6'],
  spend_limit: {
    amount: '50.00',
    cycle: 'monthly'
  },
  rate_limit: {
    rpm: 60
  }
});

// Save this immediately - the full key is only shown once
console.log('Spend key:', spendKey.key);
console.log('Key ID:', spendKey.spend_key_id);
```

> [!WARNING]
>
> The full key value is only returned when you create or rotate a spend key. Store it securely right away.

### Spend key options

| Parameter | Options | Description |
| - | - | - |
| `allowed_providers` | Array of provider names, or `null` for all | Restrict which providers can be used |
| `allowed_models` | Array of model IDs, or `null` for all | Restrict which models can be used |
| `request_shape` | `openai`, `anthropic` | Request format (default: `openai`) |
| `spend_limit` | `{ amount, cycle }` | Max spend per cycle (`daily`, `weekly`, `monthly`, `total`) |
| `request_limit` | `{ count, cycle }` | Max requests per cycle |
| `rate_limit` | `{ rpm, burst? }` | Requests per minute, with optional burst allowance |
| `expires_at` | ISO 8601 date, or `null` | Auto-expire the key after a date |
| `status` | `active`, `paused` | Pause a key without revoking it |

## Use a Spend Key

Spend keys work anywhere an OpenAI API key is accepted. Point the tool at Lava's base URL and use the spend key as the API key.

### With the OpenAI SDK

```typescript theme={null}
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: spendKey.key,
  baseURL: 'https://api.lava.so/v1'
});

const completion = await openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }]
});
```

### With the Anthropic SDK

For Anthropic-shaped requests, create the key with `request_shape: 'anthropic'`:

```typescript theme={null}
const anthropicKey = await lava.spendKeys.create({
  name: 'Agent - Anthropic',
  request_shape: 'anthropic',
  allowed_providers: ['anthropic'],
  spend_limit: { amount: '100.00', cycle: 'monthly' }
});
```

```typescript theme={null}
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: anthropicKey.key,
  baseURL: 'https://api.lava.so'  // No /v1 — Anthropic SDK appends it
});

const message = await anthropic.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }]
});
```

## Update a Spend Key

Change restrictions on an existing key without rotating the key itself:

```typescript theme={null}
await lava.spendKeys.update(spendKey.spend_key_id, {
  allowed_models: ['gpt-4o-mini'],  // Restrict to a cheaper model
  spend_limit: { amount: '100.00', cycle: 'monthly' }  // Increase limit
});
```

## Rotate a Key

Generate a new key value for the same spend key. The old key stops working immediately:

```typescript theme={null}
const rotated = await lava.spendKeys.rotate(spendKey.spend_key_id);
console.log('New key:', rotated.key);  // Full key, shown once
```

## Monitor Spend

Check current spend and usage for a key:

```typescript theme={null}
const keys = await lava.spendKeys.list();

for (const key of keys.data) {
  console.log(`${key.name}: $${key.current_spend} spent (limit: $${key.spend_limit?.amount ?? 'none'})`);
  console.log(`  ${key.current_requests} requests, last used: ${key.last_used_at ?? 'never'}`);
}
```

## Revoke a Key

Permanently disable a spend key:

```typescript theme={null}
await lava.spendKeys.revoke(spendKey.spend_key_id);
```

## What's Next?

> [card] [Spend Key Setup Guides](https://lava.so/docs/guides/spend-key-setup-guides.md)
>
> Step-by-step setup for Cursor, Claude Code, Vercel AI SDK, and more

> [card] [AI Spend Overview](https://lava.so/docs/guides/ai-spend-keys.md)
>
> How AI Spend works, dashboard features, and team management

> [card] [Route Traffic](https://lava.so/docs/agents/route-traffic.md)
>
> Forward requests through the gateway with usage tracking

> [card] [SDK Reference](https://lava.so/docs/sdk/nodejs.md)
>
> Full spend key API documentation


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