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

# BYOK: Bring Your Own Key

> Use your own LLM provider API keys with ARouter for direct control over rate limits, costs, and provider access.

## Overview

ARouter supports both platform credits and the option to bring your own provider keys (BYOK). When you use your own keys, requests are routed through your provider account while keeping all ARouter features — unified API, failover, analytics, and spend controls.

Your provider keys are securely encrypted and automatically prioritized for routing. No code changes needed — just add your keys in the dashboard and your existing ARouter API key works as before.

## How It Works

```
Your App → ARouter API (your ARouter key) → Provider (your BYOK key)
```

1. Add your provider API key in **Settings → Integrations**.
2. ARouter automatically uses your key for that provider.
3. If your key is unavailable, ARouter can fall back to platform keys (configurable).
4. Usage is tracked separately: BYOK vs. platform.

## Supported Providers

ARouter supports BYOK for any provider with one of these credential types:

| Credential Type | Providers                                           | Required Fields                        |
| --------------- | --------------------------------------------------- | -------------------------------------- |
| **API Key**     | OpenAI, Anthropic, DeepSeek, xAI, Mistral, and more | API key                                |
| **Azure**       | Azure OpenAI                                        | API key, endpoint URL, deployment name |
| **Bedrock**     | AWS Bedrock                                         | Access key, secret key, region         |
| **Vertex AI**   | Google Vertex AI                                    | Service account JSON, region           |

## Adding a BYOK Key

### Dashboard

1. Go to **Settings → Integrations**.
2. Click **Add Provider Key**.
3. Select your provider and credential type.
4. Enter your key/credentials.
5. (Optional) Click **Test Key** to verify it works.
6. Click **Save**.

### Advanced Options

When adding a key, you can configure:

| Option                   | Description                                                      | Default              |
| ------------------------ | ---------------------------------------------------------------- | -------------------- |
| **Label**                | A name for this key (e.g. "Production")                          | —                    |
| **Always use this key**  | Never fall back to platform keys                                 | Off (allow fallback) |
| **Weight**               | Routing weight when you have multiple keys for the same provider | 1                    |
| **RPM Limit**            | Max requests per minute for this key                             | Unlimited            |
| **Base URL**             | Custom endpoint URL                                              | Provider default     |
| **Region**               | Preferred region for routing                                     | Any                  |
| **Supported Models**     | Restrict this key to specific models                             | All models           |
| **Daily/Monthly Budget** | Spending limit in USD                                            | Unlimited            |

## Fallback Behavior

By default, if your BYOK key encounters a rate limit or error, ARouter falls back to platform keys seamlessly. You can change this per key:

| Fallback Policy     | Behavior                                            |
| ------------------- | --------------------------------------------------- |
| **Allow** (default) | Fall back to platform keys when BYOK is unavailable |
| **Deny**            | Reject the request if BYOK key is unavailable       |

Enable **"Always use this key"** in the dashboard to set deny fallback.

## Multiple Keys

You can add multiple BYOK keys for the same provider. ARouter uses weighted random selection across all available keys. Configure the **weight** field to control traffic distribution.

## BYOK Usage Tracking

BYOK requests are tracked separately in your usage dashboard:

* **BYOK Requests** — number of requests using your keys
* **Estimated BYOK Spend** — estimated cost based on provider pricing
* **Platform Spend** — cost of requests using platform keys

The per-model usage table shows a **Source** column indicating whether each model's requests came from BYOK, platform, or a mix.

## Azure Configuration

For Azure OpenAI, provide your key configuration as JSON:

```json theme={null}
{
  "api_key": "your-azure-api-key",
  "endpoint_url": "https://your-resource.openai.azure.com/openai/deployments/your-deployment/chat/completions?api-version=2024-08-01-preview",
  "deployment_name": "your-deployment-name"
}
```

## AWS Bedrock Configuration

For AWS Bedrock, provide your AWS credentials:

```json theme={null}
{
  "access_key": "AKIAIOSFODNN7EXAMPLE",
  "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "region": "us-east-1"
}
```

## Google Vertex AI Configuration

For Vertex AI, provide your service account credentials:

```json theme={null}
{
  "service_account_json": "{...your service account JSON...}",
  "region": "us-central1"
}
```

## Debugging BYOK Issues

If BYOK requests fail:

1. Go to **Settings → Integrations** and check the key health status.
2. Click the key to see the last error message.
3. Use the **Test Key** button to verify the key is still valid.
4. Check the **Usage** page for BYOK-specific error rates.

Common issues:

| Symptom                 | Cause                              | Fix                                                |
| ----------------------- | ---------------------------------- | -------------------------------------------------- |
| `invalid x-api-key`     | Key is expired or revoked          | Generate a new key from your provider              |
| Key shows unhealthy     | Too many errors triggered cooldown | Wait for cooldown to expire, or edit and re-enable |
| Requests not using BYOK | Provider/model mismatch            | Check the key's supported models and region        |
| Fallback to platform    | BYOK key rate-limited              | Increase RPM limit or add more keys                |