@lavapayments/nodejs SDK provides a typed client for the Lava AI Gateway: routing requests, tracking your usage, managing secret keys and spend keys, and generating forward tokens.
Installation
Initialize
Resources
Plus utility methods:
gateway()— Make requests through the gateway in a single callgenerateForwardToken()— Create authentication tokens for manual requestsLava.login()— Browser-based CLI authentication (static). Deprecated: create a secret key in the dashboard insteadLava.exchangeAuthCode()— Exchange auth code for credentials (static). Deprecated withLava.login()providers.*— Pre-configured URLs for 27 AI providers
Gateway Requests
Thegateway() method makes a request through Lava’s gateway in a single call. It handles forward token generation, URL construction, and body serialization automatically.
Parameters
With Format Translation (Rewrite)
Useformat to send requests in one LLM format and have Lava translate to the provider’s native format automatically. The provider format is auto-detected from the target URL.
openai, anthropic, google, bedrock. See Rewrite Proxy for details on format translation.
With Custom Headers
Some providers require additional headers. Pass them viaoptions.headers — the Authorization header is always set to the forward token automatically.
Pass the raw provider URL to
gateway() (e.g., https://api.openai.com/v1/chat/completions), not lava.providers.* URLs. The method constructs the forwarding URL internally.The
gateway() method returns parsed JSON. For streaming responses, use generateForwardToken() with manual fetch() instead.Authentication
Using Your Secret Key (Simplest)
The simplest way to authenticate is to pass your secret key directly, with no forward token. Costs are charged to your Lava wallet:gateway() method, which handles this automatically.
Generating Forward Tokens
A forward token is a base64-encoded JSON that bundles your secret key with optional request settings. Pass it in theAuthorization header in place of your secret key.
Gateway authentication: equivalent to sending your secret key directly. Costs are charged to your Lava wallet:
Unmanaged mode (bring your own key) lets you use Lava’s proxy for usage tracking and analytics without setting up wallet billing. You supply your own provider API key; the AI provider charges your account directly. Lava may still charge a service fee for metering.
CLI Authentication (Deprecated)
Lava.login() authenticates from a script by opening the browser, waiting for the user to authorize, and returning credentials:
Lava.login() loads an existing active Secret Key. New developer Secret Key
creation is temporarily paused for all accounts. If no key exists, login
returns a FORBIDDEN error instead of creating one. Existing keys continue
to work.
If you already have an authorization code (from a custom callback flow), exchange it directly:
Key Management
Spend Keys
Spend keys give scoped access to your wallet for AI requests:Model Discovery
List available AI models in OpenAI-compatible format. When authenticated with a spend key, results are filtered by the key’s allowed models and providers:Usage
List Requests
Every request routed through the gateway is recorded with its provider, model, token counts, and cost:Get Usage Statistics
Common Patterns
Pagination
All list methods support cursor-based pagination:Error Handling
Gateway Flow Example
A minimal integration for developers using Lava as an AI proxy:The SDK automatically detects test vs production mode based on your secret key prefix:
aks_test_*routes to sandbox (sandbox-api.lava.so)- Other prefixes route to production (
api.lava.so)
Next Steps
API Reference
Complete API documentation with all parameters and response types
Forward Proxy
Route AI requests through Lava’s proxy