Authenticate an Agent - Lava Documentation

Documentation Index

Fetch the complete documentation index at: /docs/llms.txt

Use this file to discover all available pages before exploring further.

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.

Looking for full SDK reference? See the Node.js SDK and Checkout SDK 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

• Claude Code

• Codex

• Manual JSON

claude mcp add lava -- npx -y @lavapayments/mcp

codex mcp add lava https://www.lava.so/mcp

Add the following to your MCP config file:

{
  "mcpServers": {
    "lava": {
      "command": "npx",
      "args": ["-y", "@lavapayments/mcp"],
      "env": {
        "LAVA_API_URL": "https://api.lava.so",
        "LAVA_APP_URL": "https://www.lava.so"
      }
    }
  }
}

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.

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

npm install @lavapayments/nodejs

2. Authenticate

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

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

If you don’t have an account yet, Lava.login() will take you through sign-up first. No separate registration step needed.

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:

const lava = new Lava(credentials.secret_key);

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

# Save to your environment
export LAVA_SECRET_KEY="aks_live_..."

Then initialize without hardcoding:

// 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:

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?

Route Traffic \ \ Route live traffic after choosing MCP or SDK flow

Bill Your Customers \ Set up usage-based pricing and checkout

Manage AI Spend \ Create scoped API keys with spend limits

SDK Reference \ Full Node.js SDK documentation