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

# Bring Your Own Key (BYOK)

> Use your own provider API keys through ARouter. BYOK routes requests directly to providers using your credentials — no ARouter markup on token costs.

<Note>
  BYOK is currently in development. Contact [support@arouter.ai](mailto:support@arouter.ai) to join the beta.
</Note>

Bring Your Own Key (BYOK) lets you register your own provider API keys with ARouter. When a request routes to a provider for which you have a registered key, ARouter uses your key instead of its shared key pool.

**Benefits:**

* **Zero markup** on token costs — pay providers directly at their list price
* **Your quota** — requests count against your own provider rate limits, not ARouter's shared pool
* **Your data policy** — your existing provider agreements and data terms apply
* **Unified gateway** — still get ARouter's routing, fallback, and observability on top

***

## How BYOK Works

```
Your Request → ARouter Gateway → [Route Selection] → Provider API (using your key)
```

1. You register provider API keys in the ARouter Dashboard
2. When ARouter routes a request to that provider, it substitutes your key
3. Your account is not charged for token costs (only ARouter service fees, if any)
4. `usage.is_byok: true` is returned in the response

***

## Registering Keys

Add provider keys in the [ARouter Dashboard](https://arouter.ai/settings/byok).

Supported providers and their key formats:

| Provider         | Key Format                   | Dashboard Label      |
| ---------------- | ---------------------------- | -------------------- |
| OpenAI           | `sk-...`                     | OpenAI API Key       |
| Anthropic        | `sk-ant-...`                 | Anthropic API Key    |
| Google (Gemini)  | `AIza...`                    | Google AI Studio Key |
| Azure OpenAI     | Endpoint + Key               | Azure OpenAI         |
| AWS Bedrock      | Access Key + Secret + Region | AWS Bedrock          |
| Google Vertex AI | Service Account JSON         | Google Vertex AI     |

***

## BYOK with Provider Ordering

Combine BYOK with `provider.order` to control when your key is used:

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "messages": [{"role": "user", "content": "Hello"}],
  "provider": {
    "order": ["OpenAI"]
  }
}
```

When `OpenAI` is in the order list and you have an OpenAI BYOK key registered, ARouter automatically uses your key for that provider.

### Partial BYOK

You can register keys for some providers while using ARouter's shared pool for others:

```json theme={null}
{
  "model": "anthropic/claude-sonnet-4.6",
  "provider": {
    "order": ["Anthropic", "AWS Bedrock"]
  }
}
```

If you have an Anthropic BYOK key, Anthropic will be tried first with your key. If you have an AWS Bedrock key, it tries next. Otherwise ARouter falls back to its shared pool.

***

## Azure OpenAI

Register your Azure OpenAI endpoint and key:

```json theme={null}
{
  "provider_name": "Azure",
  "azure_endpoint": "https://your-resource.openai.azure.com",
  "azure_api_key": "your-azure-key",
  "azure_deployment": "gpt-5-4"
}
```

Then route to it:

```json theme={null}
{
  "model": "openai/gpt-5.4",
  "provider": {
    "order": ["Azure"]
  }
}
```

***

## AWS Bedrock

Two authentication options:

**Option 1: Bedrock API Keys (recommended)**

```json theme={null}
{
  "provider_name": "Bedrock",
  "aws_access_key_id": "AKIA...",
  "aws_secret_access_key": "your-secret",
  "aws_region": "us-east-1"
}
```

**Option 2: AWS Credentials**

```json theme={null}
{
  "provider_name": "Bedrock",
  "aws_credentials": {
    "access_key_id": "AKIA...",
    "secret_access_key": "...",
    "session_token": "...",
    "region": "us-east-1"
  }
}
```

***

## Google Vertex AI

```json theme={null}
{
  "provider_name": "VertexAI",
  "vertex_service_account": {
    "type": "service_account",
    "project_id": "your-project",
    "private_key_id": "...",
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...",
    "client_email": "your-sa@your-project.iam.gserviceaccount.com"
  }
}
```

***

## Identifying BYOK Requests

Responses include `is_byok: true` in the `usage` object when your key was used:

```json theme={null}
{
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 45,
    "total_tokens": 165,
    "cost": 0.00,
    "is_byok": true
  }
}
```

When `is_byok: true`, `usage.cost` reflects your direct provider cost (not ARouter markup).

***

## Key Priority and Fallback

| Scenario                                     | Behavior                                                           |
| -------------------------------------------- | ------------------------------------------------------------------ |
| BYOK key registered for provider             | Use your key                                                       |
| BYOK key registered but provider unavailable | Fall back to ARouter shared pool (unless `allow_fallbacks: false`) |
| No BYOK key for provider                     | Use ARouter shared pool                                            |
| `allow_fallbacks: false` + no BYOK key       | Request fails with 404                                             |

***

## Debugging BYOK Issues

Check the Activity page in the Dashboard to see which key was used for each request. Common errors:

| Error              | Cause                           | Fix                                                     |
| ------------------ | ------------------------------- | ------------------------------------------------------- |
| `401 Unauthorized` | Invalid or expired provider key | Rotate key in Dashboard Settings                        |
| `403 Forbidden`    | Key lacks required permissions  | Check provider IAM settings                             |
| `quota_exceeded`   | Your provider quota exhausted   | Upgrade provider plan or remove BYOK to use shared pool |