# Bring Your Own Key (BYOK)

Use your own LLM provider API keys with X-Engine for direct billing, custom rate limits, and full cost control.

---

## How BYOK Works

When you register your own API key, X-Engine uses it for provider calls instead of the platform key. You pay the provider directly, X-Engine charges only for infrastructure (routing, caching, memory, telemetry).

```
Your App → X-Engine (routing + intelligence) → Provider (your API key)
                                                    ↓
                                            Billed to YOUR account
```

## Setup

### 1. Register a BYOK Provider

```bash
curl -X POST https://api.xantly.com/v1/byok/providers \
  -H "Authorization: Bearer $XANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "openai",
    "api_key": "sk-your-openai-key",
    "is_active": true,
    "priority": 1
  }'
```

Supported providers: `openai`, `anthropic`, `groq`, `deepseek`, `nvidia`, `google`.

### 2. Make Requests as Usual

No changes needed, X-Engine automatically detects and uses your BYOK key:

```bash
curl -X POST https://api.xantly.com/v1/chat/completions \
  -H "Authorization: Bearer $XANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

### 3. Check Which Key Was Used

Every response includes a `cost_attribution` field:

```json
{
  "xantly_metadata": {
    "cost_attribution": "byok",
    "provider_used": "openai",
    "cost_usd": 0.0023
  }
}
```

- `"cost_attribution": "byok"`, your key was used, you pay the provider directly
- `"cost_attribution": "xantly"`, platform key was used, billed through X-Engine

## Multiple Providers

Register keys for multiple providers to enable intelligent routing across your own accounts:

```bash
# Register OpenAI key
curl -X POST https://api.xantly.com/v1/byok/providers \
  -H "Authorization: Bearer $XANTLY_API_KEY" \
  -d '{"provider": "openai", "api_key": "sk-...", "priority": 1}'

# Register Anthropic key
curl -X POST https://api.xantly.com/v1/byok/providers \
  -H "Authorization: Bearer $XANTLY_API_KEY" \
  -d '{"provider": "anthropic", "api_key": "sk-ant-...", "priority": 2}'
```

X-Engine's BaRP router selects the optimal model across ALL your registered providers, respecting priority order for cost-equivalent options.

## BYOK + Audio/Images/Moderations

BYOK keys also apply to proxy endpoints:

| Endpoint | BYOK Provider |
|----------|---------------|
| `/v1/audio/transcriptions` | OpenAI (Whisper) |
| `/v1/audio/speech` | OpenAI (TTS) |
| `/v1/images/generations` | OpenAI (DALL-E) |
| `/v1/moderations` | OpenAI |

If no BYOK key is registered for OpenAI, the platform key is used as fallback.

## Security

- API keys are encrypted at rest (AES-256-GCM)
- Keys are never logged or exposed in responses
- Keys are never visible after creation, only the provider and status are returned
- Rotate keys anytime via `PUT /v1/byok/providers/:id`

## Cost Savings

With BYOK, you get:
- **Direct provider pricing**: no markup on token costs
- **Volume discounts**: your provider tier applies
- **Full cost visibility**: see exact costs in Mission Control
- **Caching savings**: X-Engine's semantic cache reduces calls regardless of key source