> ## Documentation Index
> Fetch the complete documentation index at: https://docs.auriko.ai/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 Auriko'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["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/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.AURIKO_API_KEY,
      baseURL: "https://api.auriko.ai/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 Auriko theme={null}
  import os
  from auriko import Client

  client = Client(
      api_key=os.environ["AURIKO_API_KEY"],
      base_url="https://api.auriko.ai/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 Auriko theme={null}
  import { Client } from "@auriko/sdk";

  const client = new Client({
      apiKey: process.env.AURIKO_API_KEY,
      baseUrl: "https://api.auriko.ai/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.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_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.auriko.ai/v1/chat/completions \
    -H "Authorization: Bearer $AURIKO_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

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

Auriko 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 [Auriko Dashboard](https://auriko.ai/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. Auriko 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 Auriko 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.auriko.ai/v1/registry/providers
```

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

## Detect provider tier

Auriko 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, Auriko stops detecting that key's tier.

## Secure your keys

Auriko 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:** Auriko decrypts your key when calling the provider, then discards it.
* **Never logged:** Auriko 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.