Proxy Authentication

LensAI provides two flexible authentication methods to suit different use cases. This guide explains both methods and how to choose the right one for your needs.

Authentication Methods Overview

Method	Use Case	Complexity	Flexibility
Composite Keys	Simple integrations, single header auth	Low	Medium
Metadata Mode	Complex scenarios, separate concerns	Medium	High

Both methods require:

A LensAI API Key from getlens.ai
A Provider API Key (OpenAI, Anthropic, or Gemini)

Method 1: Composite Keys

Composite keys combine your provider API key and LensAI key into a single authentication credential.

Basic Format

PROVIDER_KEY$LENSAI_KEY

Example:

sk-proj-abc123xyz456$lens-key-789def

Extended Format with Tracking Parameters

Add optional tracking parameters to monitor usage by agent, customer, or session:

PROVIDER_KEY$LENSAI_KEY[$AGENT_KEY][$CUSTOMER_KEY][$SESSION_KEY]

Parameters:

PROVIDER_KEY (required): Your LLM provider API key
LENSAI_KEY (required): Your LensAI API key
AGENT_KEY (optional): Identifier for the AI agent/application
CUSTOMER_KEY (optional): Identifier for the end customer
SESSION_KEY (optional): Identifier for the conversation session

Example with all parameters:

sk-proj-abc123$lens-key-789$agent-chatbot$customer-acme-corp$session-20250119-001

Usage Examples

OpenAI

curl -X POST "https://proxy.getlens.ai/v1/llm/openai/chat/completions" \
    -H "Authorization: Bearer sk-proj-YOUR_KEY$YOUR_LENSAI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-4o-mini",
        "messages": [{"role": "user", "content": "Hello!"}]
    }'

Anthropic (Claude)

curl -X POST "https://proxy.getlens.ai/v1/llm/anthropic/messages" \
    -H "x-api-key: sk-ant-YOUR_KEY$YOUR_LENSAI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "claude-3-haiku-20240307",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hello!"}]
    }'

Gemini

curl -X POST "https://proxy.getlens.ai/v1/llm/gemini/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: AIza-YOUR_KEY$YOUR_LENSAI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "contents": [{
        "parts": [{"text": "Hello!"}]
        }]
    }'

Composite Key with Tracking Parameters

Track usage by agent, customer, and session:

// Track by agent and customer
const agentId = 'support-chatbot';
const customerId = 'customer-12345';
const sessionId = `session-${Date.now()}`;

const compositeKey = `${openaiKey}$${lensaiKey}$${agentId}$${customerId}$${sessionId}`;

const client = new OpenAI({
  apiKey: compositeKey,
  baseURL: 'https://proxy.getlens.ai/v1/llm/openai',
});

This allows you to:

Filter metrics by agent, customer, or session in your analytics
Track costs per customer or per application
Debug issues by correlating logs with specific sessions

Method 2: Metadata Mode

Metadata mode separates authentication from tracking by placing LensAI-specific fields in the request body's metadata field.

When to Use Metadata Mode

Separation of concerns: Keep auth and tracking data separate
Complex integrations: When modifying headers is difficult
Dynamic routing: When you want to change provider keys per request
Multi-tenant applications: Different customers use different provider keys

Metadata Fields

Add these fields to your request body under a metadata object:

Field	Required	Description
`cts_provider_key`	Yes	Your LLM provider API key
`cts_agent_id`	No	Agent/application identifier
`cts_customer_id`	No	Customer identifier
`cts_session_id`	No	Session identifier

Authentication Header in Metadata Mode

Use your LensAI key directly in the authentication header:

For OpenAI:

Authorization: Bearer YOUR_LENSAI_KEY

For Anthropic (Claude):

x-api-key: YOUR_LENSAI_KEY

For Gemini:

x-goog-api-key: YOUR_LENSAI_KEY

Usage Examples

OpenAI

curl -X POST "https://proxy.getlens.ai/v1/llm/openai/chat/completions" \
-H "Authorization: Bearer YOUR_LENSAI_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}],
    "metadata": {
        "cts_provider_key": "sk-proj-YOUR_OPENAI_KEY",
        "cts_agent_id": "support-chatbot",
        "cts_customer_id": "customer-12345",
        "cts_session_id": "session-20250119-001"
    }
}'

Anthropic (Claude)

curl -X POST "https://proxy.getlens.ai/v1/llm/anthropic/messages" \
    -H "x-api-key: YOUR_LENSAI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "claude-3-haiku-20240307",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hello!"}],
        "metadata": {
            "cts_provider_key": "sk-ant-YOUR_ANTHROPIC_KEY",
            "cts_agent_id": "support-chatbot",
            "cts_customer_id": "customer-12345"
        }
    }'

Gemini

curl -X POST "https://proxy.getlens.ai/v1/llm/gemini/v1beta/models/gemini-2.5-flash:generateContent" \
    -H "x-goog-api-key: YOUR_LENSAI_KEY" \
    -H "Content-Type: application/json" \
    -d '{
        "contents": [{"parts": [{"text": "Hello!"}]}],
        "metadata": {
            "cts_provider_key": "AIza-YOUR_GEMINI_KEY",
            "cts_agent_id": "support-chatbot"
        }
    }'

Priority Resolution

When both authentication methods are present in a request, LensAI uses priority-based resolution:

Priority Order (Highest to Lowest)

Metadata fields (metadata.cts_provider_key, etc.)
Composite key (from Authorization/x-api-key/x-goog-api-key header)

Resolution Rules

If metadata.cts_provider_key is present, it takes precedence
Metadata tracking fields override composite key tracking parameters
LensAI automatically cleans cts_* fields from the request before forwarding to the LLM provider

Example: Metadata Overrides Composite Key

// This request uses metadata, composite key is ignored
const response = await client.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
  metadata: {
    cts_provider_key: process.env.OPENAI_KEY_A, // This is used
  }
});

// Even though the client was initialized with a composite key:
const client = new OpenAI({
  apiKey: `${process.env.OPENAI_KEY_B}$${process.env.LENSAI_KEY}`, // This is ignored
  baseURL: 'https://proxy.getlens.ai/v1/llm/openai',
});

Result: The request uses OPENAI_KEY_A from metadata, not OPENAI_KEY_B from the composite key.

Choosing the Right Method

Use Case	Recommended Method	Why
Simple integration with one provider	Composite Keys	Minimal setup, single credential
Multi-tenant app with different provider keys	Metadata Mode	Dynamic per-request provider selection
Need to separate auth from tracking	Metadata Mode	Clean separation of concerns
Using standard LLM SDKs without modification	Composite Keys	Works with existing SDK patterns
Complex enterprise requirements	Metadata Mode	Maximum flexibility and control

Proxy Authentication

On this page