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

# Authenticate an Agent

> Choose the right auth flow for MCP-hosted agents versus SDK code

This guide covers two different agent setup paths that should not be conflated:

* **MCP flow**: your host already runs the Lava MCP server, and the agent should authenticate the current MCP session with `login`
* **SDK flow**: you are writing Node.js agent code and want to use a secret key created in the dashboard

Choose one path and follow only that path.

> [!WARNING]
>
> New developer Secret Key creation is temporarily paused for all accounts.
> SDK/CLI and external MCP login can reuse existing credentials, but cannot
> issue a new Secret Key. Existing keys and Lava Desktop's internal execution
> credentials continue to work.
>
> If an external MCP OAuth exchange needs a new key, the token endpoint returns
> HTTP 400 with `invalid_grant` and an explanation of the pause. Retrying login
> does not bypass it.

> [!TIP]
>
> Looking for full SDK reference? See the [Node.js SDK](https://lava.so/docs/sdk/nodejs.md) and [Checkout SDK](https://lava.so/docs/sdk/checkout.md) pages for complete method documentation.

## Prerequisites

* Node.js 18+
* A terminal

## MCP flow

Use this when the agent is running inside Claude Code, Claude Desktop, Cursor, or another MCP-capable host with the Lava MCP server configured.

### 1. Install the MCP server

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add lava -- npx -y @lavapayments/mcp
> ```

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add lava https://www.lava.so/mcp
> ```

> [tab] Manual JSON
>
> Add the following to your MCP config file:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "lava": {
>       "command": "npx",
>       "args": ["-y", "@lavapayments/mcp"],
>       "env": {
>         "LAVA_API_URL": "https://api.lava.so",
>         "LAVA_APP_URL": "https://www.lava.so"
>       }
>     }
>   }
> }
> ```

While issuance is paused, this flow requires an existing credential.

### 2. Authenticate the MCP session

Ask the agent to call:

* `login` to authenticate via the Lava browser login flow
* `prompt` to send chat completions to any AI model (all models use OpenAI format)
* `call` to execute any API call through the gateway (non-LLM APIs or native provider format)
* `search` to find available API providers by natural language query
* `get_provider_docs` to fetch upstream API documentation for a provider

`login` loads your merchant credentials and auto-provisions a spend key for gateway access. No manual token generation needed.

> [!NOTE]
>
> Use the MCP flow if your goal is to operate Lava from an agent host. Do not import the SDK just to get credentials when the MCP is already available.

## SDK flow

Use this when you are writing application or CLI code yourself and want to authenticate from Node.js.

### 1. Install the SDK

```bash theme={null}
npm install @lavapayments/nodejs
```

### 2. Get a secret key from the dashboard

Secret keys live under **Dashboard > Gateway > Secrets**. Use your existing key (`aks_live_...`) if you have one.

> [!NOTE]
>
> New developer Secret Key creation is paused, and **Secrets** shows a
> request-access notice in place of key management. Email
> [support@lava.so](mailto:support@lava.so) to get API access for your
> account. Existing keys keep working.

### 3. Initialize the SDK

Store the key in your environment or a secrets manager, then initialize the client:

```bash theme={null}
# Save to your environment
export LAVA_SECRET_KEY="aks_live_..."
```

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

// Reads LAVA_SECRET_KEY from environment automatically
const lava = new Lava();
```

Or pass the key explicitly:

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

const lava = new Lava('aks_live_...');
```

## Deprecated: Browser Login From the SDK

> [!WARNING]
>
> `Lava.login()` and `Lava.exchangeAuthCode()` are deprecated in favor of a
> secret key created in the dashboard. Both keep working for existing scripts
> until a future major version removes them.

`Lava.login()` opens your browser, lets you log in, and returns your existing API credentials.

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

const credentials = await Lava.login();

console.log(credentials);
// {
//   secret_key: 'aks_live_...',
//   secret_key_id: 'sk_...',
//   merchant_id: 'mer_...',
//   wallet_id: 'wa_...'
// }

const lava = new Lava(credentials.secret_key);
```

Under the hood, a local HTTP server starts on a random port, your browser opens Lava's authorization page, you log in and click "Authorize", the credentials flow back to your terminal, and the local server shuts down.

> [!NOTE]
>
> Creating an account does not bypass the issuance pause. If no Secret Key
> exists, SDK login returns `FORBIDDEN`.

If you're building a custom auth flow (for example, handling the browser callback yourself), `Lava.exchangeAuthCode()` exchanges the one-time code directly. Auth codes expire after 60 seconds and can only be used once.

```typescript theme={null}
const credentials = await Lava.exchangeAuthCode({
  code: 'your_one_time_auth_code'
});
```

## What's Next?

> [card] [Route Traffic](https://lava.so/docs/agents/route-traffic.md)
>
> Route live traffic after choosing MCP or SDK flow

> [card] [Bill Your Customers](https://lava.so/docs/agents/bill-customers.md)
>
> Set up usage-based pricing and checkout

> [card] [Manage AI Spend](https://lava.so/docs/agents/manage-spend.md)
>
> Create scoped API keys with spend limits

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


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