Authenticate an Agent

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.

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.

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"
      }
    }
  }
}

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.

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. Get a secret key from the dashboard

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

New developer Secret Key creation is paused, and Secrets shows a request-access notice in place of key management. Email 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:

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

import { Lava } from '@lavapayments/nodejs';

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

Or pass the key explicitly:

import { Lava } from '@lavapayments/nodejs';

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

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.

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.

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.

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

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

Get Started

Guides

AI Gateway

Prerequisites

MCP flow

1. Install the MCP server

2. Authenticate the MCP session

SDK flow

1. Install the SDK

2. Get a secret key from the dashboard

3. Initialize the SDK

What’s Next?

Route Traffic

Bill Your Customers

Manage AI Spend

SDK Reference

​Prerequisites

​MCP flow

​1. Install the MCP server

​2. Authenticate the MCP session

​SDK flow

​1. Install the SDK

​2. Get a secret key from the dashboard

​3. Initialize the SDK

​Deprecated: Browser Login From the SDK

​What’s Next?

Route Traffic

Bill Your Customers

Manage AI Spend

SDK Reference

Prerequisites

MCP flow

1. Install the MCP server

2. Authenticate the MCP session

SDK flow

1. Install the SDK

2. Get a secret key from the dashboard

3. Initialize the SDK

Deprecated: Browser Login From the SDK

What’s Next?