Using Helicone Cloud AI Gateway? Authentication is automatically handled for you - no setup required! This guide is only for self-hosted deployments.Get started with Cloud →
To deploy a secure self-hosted AI Gateway, you have two options:
  1. Secure Network Deployment - Deploy in a secure network (VPN, private cloud) where network-level access control provides security
  2. Public Network with Authentication - Deploy on a public network and use Helicone authentication to secure your gateway
If you’re deploying in a secure network with proper access controls, you can skip the rest of this guide. Authentication is only required for public deployments or when you need user-level access control.
The AI Gateway integrates with Helicone to provide secure authentication for your AI requests. When enabled, the gateway requires valid Helicone API keys for all requests, ensuring only authorized users can access your provider API keys.

​
Quick Start

1

Set your Helicone API key

Add your Helicone API key as an environment variable:
export HELICONE_CONTROL_PLANE_API_KEY=sk-helicone-your-api-key
2

Enable Helicone authentication

Create or update your ai-gateway-config.yaml:
helicone:
  # Set to `features: observability` to enable both auth and observability
  features: auth

routers:
  my-router:
    load-balance:
      chat:
        strategy: latency
        providers:
          - openai
          - anthropic
3

Start the gateway

npx @helicone/ai-gateway@latest --config ai-gateway-config.yaml
4

Test with authentication

Now you must include your Helicone API key in the request.
curl -X POST http://localhost:8080/router/my-router/chat/completions \
  -H "Authorization: Bearer sk-helicone-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
✅ Your request is authenticated and routed to the provider!
Security Warning: Without authentication enabled or limited network access, anyone with access to your AI Gateway can use your provider API keys. Enable Helicone authentication to secure your deployment.

​
Authentication Usage

Configure helicone.features to control authentication and observability:
  • none - No authentication or observability
  • auth - Authentication only
  • observability - Authentication + observability
  • all - Authentication + all Helicone features
When authentication is enabled, include your Helicone API key with every request: 
curl -X POST http://localhost:8080/router/my-router/chat/completions \
  -H "Authorization: Bearer sk-helicone-abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
The gateway validates keys in real-time through a persistent WebSocket connection to Helicone’s control plane. Keys are cached locally for resilience during network issues and for performance.
For complete configuration options, see the Configuration Reference.

​
Use Cases

Use case: Production deployment requiring authentication.
helicone:
  # Set to `features: observability` to enable observability and auth
  features: auth
Environment variables:
HELICONE_CONTROL_PLANE_API_KEY=sk-helicone-your-api-key
Result: All requests require valid Helicone API keys for access.

​
How Authentication Works

When enabled, the AI Gateway connects to Helicone’s control plane for real-time authentication validation.
1

WebSocket Connection

Gateway establishes persistent connection to Helicone control plane with automatic reconnection and exponential backoff
2

API Key Sync

Authorized API keys and user data are cached locally for fast validation and resilience during network issues
3

Request Validation

Incoming requests are validated against cached keys with graceful degradation - cached keys continue working during temporary connectivity issues
4

Access Control

Only requests with valid Helicone API keys are allowed through to your provider APIs

​
Security

Access Control: Requests without valid Helicone API keys are rejected with 401 Unauthorized. Your provider API keys (OpenAI, Anthropic, etc.) remain secure in the gateway environment and are never transmitted to Helicone. Secure Communication: All data transmission to Helicone uses TLS encryption for secure key validation.