Forward Proxy & Authentication

This page covers how to authenticate with Lava, construct proxy URLs, and handle responses and errors.

Prerequisites: You need a Lava merchant account and a forward token. See Quickstart: Make Your First Request to get started.

Forward Tokens

Lava AI Gateway uses a forward token system for authenticating API requests. A forward token is a base64-encoded JSON string that combines your merchant credentials with a specific customer connection and pricing configuration.

Token Structure

A forward token encodes four fields into a single credential:

Component	Purpose	Obtained From
Secret Key	Your Lava API key	Generated in merchant dashboard
Connection ID	Links to a customer	Returned from checkout completion
Meter Slug	Specifies pricing configuration	Meter configuration in dashboard
Provider Key (Optional)	Enable BYOK (Bring Your Own Key)	Your own provider credentials

Self token vs. customer token: The self forward token from Gateway > Secrets points to an auto-created connection and zero-fee meter that charge your own wallet — use it for development and internal usage. To charge customers, generate tokens with their connection_id and your pricing meter_slug.

Generating a Forward Token

SDK
TypeScript
Python
cURL

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

const lava = new Lava();

const forwardToken = lava.generateForwardToken({
  connection_id: 'conn_xyz789',
  meter_slug: 'my-meter'
});

const tokenData = {
  secret_key: 'aks_live_abc123...',
  connection_id: 'conn_xyz789...',
  meter_slug: 'my-meter',
  provider_key: null
};

const forwardToken = btoa(JSON.stringify(tokenData));

import base64, json

token_data = {
    "secret_key": "aks_live_abc123...",
    "connection_id": "conn_xyz789...",
    "meter_slug": "my-meter",
    "provider_key": None
}

forward_token = base64.b64encode(json.dumps(token_data).encode()).decode()

# Generate token (base64-encoded JSON)
FORWARD_TOKEN=$(echo -n '{"secret_key":"aks_live_abc123...","connection_id":"conn_xyz789...","meter_slug":"my-meter","provider_key":null}' | base64)

Constructing the Request URL

Lava routes requests by wrapping the provider’s API endpoint (e.g., OpenAI’s chat completions URL) as a query parameter using Lava’s forward endpoint:

https://api.lavapayments.com/v1/forward?u=<PROVIDER_URL>

See Supported Providers for the full list of providers you can access with Lava AI Gateway.

As a best practice, the provider URL should be URL-encoded.

Provider Examples

The pattern is the same for every provider — only the URL, body format, and provider-specific headers change.

OpenAI
Anthropic
Google Gemini

const response = await fetch(
  'https://api.lavapayments.com/v1/forward?u=' +
    encodeURIComponent('https://api.openai.com/v1/chat/completions'),
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${forwardToken}`
    },
    body: JSON.stringify({
      model: 'gpt-4o-mini',
      messages: [{ role: 'user', content: 'Hello!' }]
    })
  }
);

const data = await response.json();
const requestId = response.headers.get('x-lava-request-id');

const response = await fetch(
  'https://api.lavapayments.com/v1/forward?u=' +
    encodeURIComponent('https://api.anthropic.com/v1/messages'),
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${forwardToken}`,
      'anthropic-version': '2023-06-01'  // Required by Anthropic
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-5-20250514',
      max_tokens: 1024,
      messages: [{ role: 'user', content: 'Hello!' }]
    })
  }
);

const data = await response.json();
const requestId = response.headers.get('x-lava-request-id');

const response = await fetch(
  'https://api.lavapayments.com/v1/forward?u=' +
    encodeURIComponent('https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent'),
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${forwardToken}`
    },
    body: JSON.stringify({
      contents: [{ parts: [{ text: 'Hello!' }] }]
    })
  }
);

const data = await response.json();
const requestId = response.headers.get('x-lava-request-id');

Provider-specific headers (like anthropic-version) are passed through unchanged. The request body uses the provider’s native format — Lava doesn’t modify it.

Streaming

Add "stream": true to your request body. Lava proxies SSE chunks in real-time without buffering — the response is identical to calling the provider directly. Usage and billing are recorded after the stream completes.

body: JSON.stringify({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
  stream: true  // That's it — everything else stays the same
})

Error Handling

Status	Cause	Retryable
401	Invalid or malformed forward token	No — check credentials
402	Insufficient credit balance	No — add funds first
429	Rate limit exceeded	Yes — back off and retry
500/502/503	Provider or Lava server error	Yes — retry with backoff

Provider error responses are forwarded unchanged — check your request body against the provider’s API docs if you see provider-level errors.

Troubleshooting

401 Unauthorized

Verify your secret key matches the dashboard, ensure the Bearer prefix is in the Authorization header, and try the self forward token from Gateway > Secrets to isolate the issue.

# Decode a forward token to inspect its contents
echo "your_forward_token" | base64 -d

CORS errors in browser

Lava blocks frontend requests to prevent token exposure. Always call Lava from your backend: Frontend → Your Backend → Lava → AI Provider.

Get Started

AI Gateway

AI Spend

Monetize

Integration

SDK

Cookbook

Comparisons

Forward Tokens

Token Structure

Generating a Forward Token

Constructing the Request URL

Provider Examples

Streaming

Error Handling

Troubleshooting

Next Steps

Supported Providers

Webhooks

Get Started

AI Gateway

AI Spend

Monetize

Integration

SDK

Cookbook

Comparisons

​Forward Tokens

​Token Structure

​Generating a Forward Token

​Constructing the Request URL

​Provider Examples

​Streaming

​Error Handling

​Troubleshooting

​Next Steps

Supported Providers

Webhooks

Forward Tokens

Token Structure

Generating a Forward Token

Constructing the Request URL

Provider Examples

Streaming

Error Handling

Troubleshooting

Next Steps