Bring your own provider key

Use provider keys to let ngrok.ai call an upstream provider with your own credentials. Provider keys are the API keys you already use with OpenAI, Google, Anthropic, and others. You can add them to ngrok.ai once, and it uses them to call those providers on your behalf, keeping keys out of your app.

For certain providers, like OpenAI and Anthropic, you can skip provider keys and use ngrok.ai inference on your credits instead.

Add a provider key

Via the ngrok dashboard

Open Providers

Head over to the Providers page and choose the provider you want from either the Built-in or Custom tab.

Add a key

Once you’re on the provider’s page, scroll down to API keys and add your key there.

Via the AI Gateway API

You can add your own API Keys for providers via the Provider Keys API:

curl -X POST https://api.ngrok.ai/provider-keys \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "openai",
    "name": "My OpenAI Key",
    "value": "sk-proj-..."
  }'

After you add a key, the dashboard only shows a redacted version (first10***last4). Make sure you keep a copy of the full key from your provider, since you won’t be able to see it again here. Provider keys are shared across your account, so you can use the same key with multiple access keys.

When a key does not have an access configuration attached, the gateway begins using this provider key immediately. To select specific keys, define failover order, or restrict providers and models, use an access key configuration.

Control access with a configuration

An access key without a configuration uses any provider keys you’ve added, so it works out of the box. If you need more control, you can attach an access key configuration. This lets you choose which key to use, set a fallback order, or limit which providers and models are available.

Add the provider key

First, make sure you’ve already added a key for the provider.

Attach the key in an access key configuration

Next, go to your access key configuration. Then add a routing rule for the provider, choose Bring your own API key, and pick the key you added in the previous step.You can add more than one key for the same provider—if one fails or hits a limit, the gateway will automatically try the next one in your list. For more details, see key selection and failover.When using the ngrok.ai API, reference the key’s ID in the configuration’s router rules:

{
  "router": {
    "rules": [
      {
        "provider": "openai",
        "steps": [
          {
            "type": "user",
            "keySelectionStrategy": "ordered",
            "keys": [{ "id": "aigpk_xxxxx" }]
          }
        ]
      }
    ]
  }
}

Assign the configuration to an access key

Navigate to the Access Keys page, and assign the configuration to the access key your app uses.

Send a request

Your app only needs to send the access key. The gateway uses it to find the right configuration, chooses the provider key, and makes the request for you:

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.ngrok.ai/v1",
    api_key="ng-xxxxx-g1-xxxxx"  # Access key, not the provider key
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)

Rotating provider keys

Rotating provider keys lets you update its value without changing its ID, so anything already using it keeps working. This means you can keep your existing configurations as they are.

Rotate the key

Update the key by sending its new value to the Provider Keys API, using your ngrok.ai API key:

curl -X POST https://api.ngrok.ai/provider-keys/aigpk_xxxxx/rotate \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My OpenAI Key",
    "value": "sk-proj-..."
  }'

Verify traffic

Send a test request with your access key. The key ID is unchanged, so there’s nothing else to update.

Common issues

Problem	What to check
Request is rejected before routing	The access key configuration may not allow the provider or model
Provider returns an auth error	The provider key may be missing, invalid, expired, or unable to call the requested model
Usage is not appearing in provider billing	The request may be using ngrok.ai inference instead of your provider key

Next steps

Access Key Configurations: Attach keys and set scope
Bring Your Own Keys: Built-in vs custom providers
Key selection and failover: Ordered key failover

Concepts

Getting Started With

SDKs

Guides

Observability

Examples

Reference

API Reference

Add a provider key

Via the ngrok dashboard

Via the AI Gateway API

Control access with a configuration

Rotating provider keys

Common issues

Next steps

​Add a provider key

​Via the ngrok dashboard

​Via the AI Gateway API

​Control access with a configuration

​Rotating provider keys

​Common issues

​Next steps

Add a provider key

Via the ngrok dashboard

Via the AI Gateway API

Control access with a configuration

Rotating provider keys

Common issues

Next steps