Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

AI Gateway API keys are the simplest way to start using the AI Gateway. Create a key, add it to your SDK configuration, and start making requests—ngrok handles the provider accounts and API keys for OpenAI and Anthropic on your behalf.
Need providers beyond OpenAI and Anthropic, or already have your own provider accounts? See Bring Your Own Keys.

​
Getting started

  1. Create an AI Gateway if you haven’t already
  2. Purchase credits—AI Gateway API Keys require prepaid credits to work
  3. Create an API key from your gateway’s API Keys tab in the dashboard
  4. Update your SDK with both the gateway URL and your key:
from openai import OpenAI

client = OpenAI(
    base_url="https://your-ai-gateway.ngrok.app/v1",  # Your AI Gateway URL
    api_key="ng-xxxxx-g1-xxxxx"                       # Your AI Gateway API Key
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
No OpenAI account, no provider API key, no Traffic Policy configuration. Your AI Gateway API Key handles authentication with the provider automatically.

​
When to use AI Gateway API Keys

Use AI Gateway API Keys when you want to:
  • Get started quickly: no provider accounts or billing setup needed
  • Use OpenAI or Anthropic: these are the currently supported providers
  • Keep things simple: built-in auth means no need to configure secrets or Traffic Policy rules
  • Let ngrok handle key management: no provider keys to rotate or secure
AI Gateway API Keys work with OpenAI and Anthropic only. For Google, DeepSeek, self-hosted models, and other providers, use Bring Your Own Keys. You can use both in the same gateway.

​
Creating keys

​
Dashboard

  1. Navigate to AI Gateways in the dashboard
  2. Select your gateway
  3. Go to the API Keys tab
  4. Click New API Key
  5. Copy the token immediately—it won’t be shown again

​
CLI

ngrok api ai-gateway-api-keys create \
  --endpoint-id ep_xxxxx \
  --description "My app"
You can find your gateway’s endpoint ID in the AI Gateways dashboard on your gateway’s detail page, or by running ngrok api endpoints list.

​
API

curl -X POST https://api.ngrok.com/ai_gateway_api_keys \
  -H "Authorization: Bearer $NGROK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Ngrok-Version: 2" \
  -d '{
    "endpoint_id": "ep_xxxxx",
    "description": "My app"
  }'

​
Managing keys

OperationCLIAPI
Listngrok api ai-gateway-api-keys listGET /ai_gateway_api_keys
Getngrok api ai-gateway-api-keys get <id>GET /ai_gateway_api_keys/{id}
Updatengrok api ai-gateway-api-keys update <id>PATCH /ai_gateway_api_keys/{id}
Deletengrok api ai-gateway-api-keys delete <id>DELETE /ai_gateway_api_keys/{id}
Create separate keys for each application or team. This way you can revoke one client’s access without affecting others, and track usage per key.

​
Things to know

​
Your key token is only shown once

When you create a key, the token (starting with ng-) is displayed exactly once. Store it somewhere safe. If you lose it, delete the key and create a new one.
If you lose your API key token, you cannot retrieve it. Delete the old key and create a new one.

​
Keys require credits

AI Gateway API Keys require prepaid credits. Credits cover ngrok’s processing fee plus the upstream provider cost (OpenAI, Anthropic). When credits run out, keys stop working until you purchase more.

​
Each key is tied to one gateway

A key only works with the specific AI Gateway it was created for. If you use it with a different gateway, you’ll get an error.

​
Invalid keys are rejected, not passed through

If you send a request with a malformed or deleted AI Gateway API Key, the request is rejected immediately. It won’t silently fall through to another authentication method. See Troubleshooting for error codes.

​
You can use ngrok/auto for automatic model selection

Set model: "ngrok/auto" and the gateway picks the best available model from OpenAI and Anthropic—no provider configuration needed: 
{
  "model": "ngrok/auto",
  "messages": [{"role": "user", "content": "Hello"}]
}

​
Attaching your own provider keys

Attach your own provider API keys directly to an AI Gateway API Key. ngrok encrypts them at rest and uses them automatically when routing requests. When you authenticate with an AI Gateway API Key, the gateway selects a provider key for each provider as follows:
  1. Keys you’ve attached to the AI Gateway API Key: used exclusively when present for that provider
  2. Provider keys in your Traffic Policy (providers[].api_keys): deprecated for standard providers, still required for custom or self-hosted providers; used only when no attached key exists for that provider
  3. ngrok-managed keys: fallback for OpenAI and Anthropic (requires credits)
See Attaching Provider Keys for setup instructions.

​
Mixing AI Gateway API Keys with your own provider keys

You can use both AI Gateway API Keys and Bring Your Own Keys in the same gateway. This is useful when you want ngrok to handle OpenAI and Anthropic, but you also need access to other providers like Google. When you authenticate with an AI Gateway API Key:
  • OpenAI and Anthropic use ngrok’s managed keys automatically
  • Any provider where you’ve configured your own keys uses those instead

​
How AI Gateway API Keys differ from other ngrok credentials

ngrok has several types of credentials, and it’s easy to mix them up:
CredentialWhat it’s for
AI Gateway API KeysYour app uses these to make AI requests through the gateway
ngrok API KeysYou use these to manage ngrok resources via the management API
ngrok Authtokensngrok agents use these to connect to the platform
Provider API KeysKeys from OpenAI, Anthropic, etc.—only needed with BYOK

​
Next steps