Set up an access key configuration

Every request to https://gateway.ngrok.ai must include an access key. Upstream provider credentials are managed in app.ngrok.ai and injected server-side based on the access key’s configuration—see Access keys vs provider keys. Access key configurations control:

Access scope: which providers and models the key may call
Routing rules: whether to pay with credits or use your stored provider keys for each provider

See Create a configuration below, or the Access Key Configurations API.

How it fits together

Your app sends an access key with each request.
The gateway loads the configuration linked to that key (or default rules if none is linked).
The AI Gateway selects upstream credentials from the configuration’s routing rules.

Default behavior

An access key with no configuration (allow-all scope) can reach any provider and model your account supports. For built-in models you can pay for with credits, an ngrok.ai key is used automatically when you have credits. To use your own provider accounts, restrict scope, or control failover, create a configuration and assign it to the key.

Create a configuration

Via the ngrok dashboard

Open app.ngrok.ai → Keys → Configurations.
Click New configuration.
Set a name and optional description.
Under Access, allow only the providers and models this key should use.
Under Routing, add a rule per provider:
- ngrok: pay with credits. ngrok.ai supplies the credentials (supported providers only)
- Bring your own API key: attach one or more stored provider keys (tried in order)
Save the configuration.
On Keys, edit an access key and assign the configuration.

Via the AI Gateway API

Create configurations with the Access Key Configurations API. Authorize the request with your AI Gateway API key.

curl -X POST https://api.ngrok.ai/access-key-configurations \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production OpenAI BYOK",
    "access": {
      "providers": { "allow": ["openai"] },
      "models": { "allow": ["openai/gpt-4o"] }
    },
    "router": {
      "rules": [
        {
          "provider": "openai",
          "steps": [
            {
              "type": "user",
              "keySelectionStrategy": "ordered",
              "keys": [{ "id": "aigpk_xxxxx" }]
            }
          ]
        }
      ]
    }
  }'

Link the configuration when creating or updating an access key:

curl -X PATCH https://api.ngrok.ai/access-keys/aigk_xxxxx \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "accessKeyConfigurationId": "aigac_xxxxx" }'

See the Access Key Configurations API reference and Access Keys API.

Routing rules

Each routing rule targets exactly one provider or one model and defines an ordered list of steps. A model rule uses the provider-qualified form, such as openai:openai/gpt-5.5, and takes precedence over a provider rule for the same provider. A configuration can have at most one rule per provider.

Step type	Meaning
`ngrok`	Pay with credits. ngrok.ai supplies the key (supported providers only)
`user`	Use attached provider keys, tried in list order

For built-in providers, you can pay with credits, bring your own key, or list your own keys first with an ngrok step after them as a fallback. The gateway uses the first step that has usable credentials. The ngrok fallback only runs when your keys hit auth errors or rate limits. When a configuration has no rule for a provider, requests to that provider are paid with credits only. Stored provider keys are not used without a rule. Custom providers require a user step with at least one provider key when the upstream requires authentication.

Multi-key failover

Attach multiple provider keys to the same routing rule step. The gateway tries them in order when a key hits a rate limit or auth error. Server errors and timeouts move to the next model instead. See Multi-key failover.

Restrict providers and models

Use the access block to limit what an access key can call:

{
  "access": {
    "providers": { "allow": ["openai", "anthropic"] },
    "models": { "allow": ["openai/gpt-4o", "anthropic/claude-sonnet-4-6"] }
  }
}

Omit access entirely for allow-all scope. An empty allow array blocks all traffic on that dimension.

Next steps

Access Keys: Create keys and assign configurations
Bring your own provider key: Store upstream credentials
Restrict providers and models: Limit what a key can call
Choose a model: Choose models in requests
Securing Your Gateway: Per-client keys and revocation

Concepts

Getting Started With

SDKs

Agents

Guides

Observability

Examples

Reference

API Reference

Set up an access key configuration

How it fits together

Default behavior

Create a configuration

Via the ngrok dashboard

Via the AI Gateway API

Routing rules

Multi-key failover

Restrict providers and models

Next steps

​How it fits together

​Default behavior

​Create a configuration

​Via the ngrok dashboard

​Via the AI Gateway API

​Routing rules

​Multi-key failover

​Restrict providers and models

​Next steps

How it fits together

Default behavior

Create a configuration

Via the ngrok dashboard

Via the AI Gateway API

Routing rules

Multi-key failover

Restrict providers and models

Next steps