> ## 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 call `Lava.login()` directly

Choose one path and follow only that path.

<Tip>
  Looking for full SDK reference? See the [Node.js SDK](/sdk/nodejs) and [Checkout SDK](/sdk/checkout) pages for complete method documentation.
</Tip>

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

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add lava -- npx -y @lavapayments/mcp
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add lava https://www.lava.so/mcp
    ```
  </Tab>

  <Tab title="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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

No pre-provisioned keys are needed — you'll authenticate in the next step.

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

<Info>
  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.
</Info>

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

`Lava.login()` opens your browser, lets you sign up or log in, and returns your API credentials automatically.

```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_...'
// }
```

<Info>
  If you don't have an account yet, `Lava.login()` will take you through sign-up first. No separate registration step needed.
</Info>

### 3. What happens under the hood

1. A local HTTP server starts on a random port
2. Your browser opens to Lava's authorization page
3. You sign up or log in and click "Authorize"
4. Credentials flow back to your terminal
5. The local server shuts down

The entire flow takes about 10 seconds.

## Initialize the SDK

Use the secret key as your SDK credential:

```typescript theme={null}
const lava = new Lava(credentials.secret_key);
```

<Tip>
  Store your credentials in environment variables or a secrets manager. You only need to run `Lava.login()` once.
</Tip>

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

Then initialize without hardcoding:

```typescript theme={null}
// Reads LAVA_SECRET_KEY from environment automatically
const lava = new Lava();
```

## Alternative: Exchange an Auth Code Directly

If you're building a custom auth flow (for example, handling the browser callback yourself), use `Lava.exchangeAuthCode()` instead:

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

Auth codes expire after 60 seconds and can only be used once.

## What's Next?

<CardGroup cols={2}>
  <Card title="Route Traffic" icon="route" href="/agents/route-traffic">
    Route live traffic after choosing MCP or SDK flow
  </Card>

  <Card title="Bill Your Customers" icon="dollar-sign" href="/agents/bill-customers">
    Set up usage-based pricing and checkout
  </Card>

  <Card title="Manage AI Spend" icon="wallet" href="/agents/manage-spend">
    Create scoped API keys with spend limits
  </Card>

  <Card title="SDK Reference" icon="code" href="/sdk/nodejs">
    Full Node.js SDK documentation
  </Card>
</CardGroup>