> ## Documentation Index
> Fetch the complete documentation index at: https://infravelle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring your own key

> Route requests through your own provider API keys.

*Bring Your Own Key (BYOK)* lets you use your own provider API keys instead of Infravelle's shared pool. You control the key, the billing relationship, and any provider-specific quotas.

## Route with BYOK

To restrict a request to your own keys, set `gateway.routing.only_byok`:

<CodeGroup>
  ```python Python OpenAI theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["INFRAVELLE_API_KEY"],
      base_url="https://api.infravelle.com/v1",
  )

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

  ```typescript TypeScript OpenAI theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
      apiKey: process.env.INFRAVELLE_API_KEY,
      baseURL: "https://api.infravelle.com/v1",
  });

  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { only_byok: true } },
  });

  console.log(response.choices[0].message.content);
  ```

  ```python Python Infravelle theme={null}
  import os
  from infravelle import Client

  client = Client(
      api_key=os.environ["INFRAVELLE_API_KEY"],
      base_url="https://api.infravelle.com/v1"
  )

  # Use only your own keys
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {"only_byok": True}}
  )

  # Use only platform keys (no BYOK)
  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
      gateway={"routing": {"only_platform": True}}
  )
  ```

  ```typescript TypeScript Infravelle theme={null}
  import { Client } from "@infravelle/sdk";

  const client = new Client({
      apiKey: process.env.INFRAVELLE_API_KEY,
      baseUrl: "https://api.infravelle.com/v1",
  });

  // Use only your own keys
  const response = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { only_byok: true } },
  });

  // Use only platform keys (no BYOK)
  const platform = await client.chat.completions.create({
      model: "gpt-4o",
      messages: [{ role: "user", content: "Hello!" }],
      gateway: { routing: { only_platform: true } },
  });
  ```

  ```bash cURL theme={null}
  # Use only your own keys
  curl https://api.infravelle.com/v1/chat/completions \
    -H "Authorization: Bearer $INFRAVELLE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {"only_byok": true}}
    }'

  # Use only platform keys (no BYOK)
  curl https://api.infravelle.com/v1/chat/completions \
    -H "Authorization: Bearer $INFRAVELLE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}],
      "gateway": {"routing": {"only_platform": true}}
    }'
  ```
</CodeGroup>

See [Routing options](/guides/routing-options#restrict-key-source) for the full constraint API.

## Understand routing behavior

Infravelle prefers your BYOK key when one exists for the requested provider. You get direct billing control and your provider tier applies.

Infravelle falls back to platform keys in two cases:

1. **Rate-limited:** your BYOK key is rate-limited and the platform key has capacity.
2. **Unavailable:** your BYOK key is unavailable at request time and a platform key exists.

Override the default with routing constraints:

* `only_byok: true` — use only your BYOK key and fail the request if unavailable.
* `only_platform: true` — ignore BYOK keys entirely.

BYOK requests count toward a monthly cap that scales with your plan. See [Plans and billing](/platform/plans#compare-plans) for caps by tier.

## Set up BYOK keys

Manage your provider keys in the [Infravelle Dashboard](https://infravelle.com/dashboard).

1. Go to **Settings > Provider Keys** in the dashboard.
2. Click **Add Provider Key**.
3. Select the provider and paste your API key.
4. Infravelle validates the key before saving.

## Manage keys via the API

You can also manage BYOK keys programmatically with an API key carrying the `byok:read` / `byok:write` scopes:

* [List BYOK providers](/api-reference/list-byok-providers) and [provider account tiers](/api-reference/get-byok-provider-tiers) — public discovery endpoints, the source of allowed `account_tier` values.
* [Create](/api-reference/create-byok-key), [list](/api-reference/list-byok-keys), [get](/api-reference/get-byok-key), [update](/api-reference/update-byok-key), and [delete](/api-reference/delete-byok-key) BYOK keys.

Submitted secrets are write-only: validated against the provider at creation, encrypted at rest, and never returned. `byok:write` changes which third-party credentials Infravelle uses for future model calls. Treat it as a sensitive permission.

## List supported providers

`GET /v1/registry/providers` returns the current list of supported providers. The endpoint is public and doesn't require authentication:

```bash cURL theme={null}
curl https://api.infravelle.com/v1/registry/providers
```

See the [Provider catalog](/api-reference/provider-catalog) reference for the full response schema.

## Detect provider tier

Infravelle detects your provider account tier on first use. The detected tier affects rate limits and routing decisions.

You can override detection:

* **Enterprise flag** — mark a key as enterprise tier in the dashboard for higher limits.
* **Manual tier** — select a specific tier for providers that require it (e.g., Google AI Studio), in the dashboard or via `account_tier` on the [create](/api-reference/create-byok-key) and [update](/api-reference/update-byok-key) endpoints.

Once you set a tier manually, Infravelle stops detecting that key's tier.

## Secure your keys

Infravelle encrypts your provider keys and isolates them per workspace.

* **Encrypted at rest:** authenticated encryption with per-workspace key isolation.
* **Masked in responses:** API responses show only a short prefix of each key.
* **Decrypted at request time only:** Infravelle decrypts your key when calling the provider, then discards it.
* **Never logged:** Infravelle never logs or persists decrypted keys.

## Control data handling

BYOK keys inherit the workspace data policy. Options: `none`, `no_training`, and `zdr` (zero data retention).

A per-request `data_policy` overrides the workspace default. Providers that don't meet the required level aren't available for routing.

See [Advanced routing](/guides/advanced-routing#data-policy) for more on data policies.