> ## 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.

# Bring your own provider key

> Add an upstream provider key and use it through the AI Gateway.

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.

<Note>
  For [certain providers](/ai-gateway/reference/model-catalog#billing-and-provider-credentials), like OpenAI and Anthropic, you can skip provider keys and use [ngrok.ai inference](/ai-gateway/guides/use-ngrok-ai-inference) on your [credits](/ai-gateway/concepts/credits) instead.
</Note>

## Add a provider key

### Via the ngrok dashboard

<Steps>
  <Step title="Open Providers">
    Head over to the [Providers](https://app.ngrok.ai/providers) page and choose the provider you want from either the **Built-in** or **Custom** tab.
  </Step>

  <Step title="Add a key">
    Once you're on the provider's page, scroll down to **API keys** and add your key there.
  </Step>
</Steps>

### Via the AI Gateway API

You can add your own API Keys for providers via the [Provider Keys API](/ai-gateway/api-reference/provider-keys/create):

```bash theme={null}
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.

<Note>
  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.
</Note>

## 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](/ai-gateway/guides/access-key-configurations). This lets you choose which key to use, set a fallback order, or limit which providers and models are available.

<Steps>
  <Step title="Add the provider key">
    First, make sure you've already [added a key](#add-a-provider-key) for the provider.
  </Step>

  <Step title="Attach the key in an access key configuration">
    Next, go to your [access key configuration](/ai-gateway/guides/access-key-configurations#create-a-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](/ai-gateway/guides/key-selection-failover).

    When using the ngrok.ai API, reference the key's ID in the configuration's router rules:

    ```json theme={null}
    {
      "router": {
        "rules": [
          {
            "provider": "openai",
            "steps": [
              {
                "type": "user",
                "keySelectionStrategy": "ordered",
                "keys": [{ "id": "aigpk_xxxxx" }]
              }
            ]
          }
        ]
      }
    }
    ```
  </Step>

  <Step title="Assign the configuration to an access key">
    Navigate to the [Access Keys](https://app.ngrok.ai/keys) page, and assign the configuration to the [access key](/ai-gateway/concepts/access-keys) your app uses.
  </Step>

  <Step title="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:

    ```python theme={null}
    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!"}]
    )
    ```
  </Step>
</Steps>

## Rotating provider keys

[Rotating provider keys](/ai-gateway/api-reference/provider-keys/rotate) 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.

<Steps>
  <Step title="Rotate the key">
    Update the key by sending its new value to the [Provider Keys API](/ai-gateway/api-reference/provider-keys/rotate), using your [ngrok.ai API key](/ai-gateway/concepts/access-keys#credentials-overview):

    ```bash theme={null}
    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-..."
      }'
    ```
  </Step>

  <Step title="Verify traffic">
    Send a test request with your access key. The key ID is unchanged, so there's nothing else to update.
  </Step>
</Steps>

## 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](/ai-gateway/guides/access-key-configurations): Attach keys and set scope
* [Bring Your Own Keys](/ai-gateway/concepts/bring-your-own-keys): Built-in vs custom providers
* [Key selection and failover](/ai-gateway/guides/key-selection-failover): Ordered key failover