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

# Bring Your Own Key (BYOK)

> Use your own API keys to call providers directly through Dedalus

BYOK lets you send requests through Dedalus using your own provider API key. The request still flows through our unified API (routing, tool calling, streaming, format normalization), but the LLM call is billed to your account with the provider.

## When to use BYOK

* You have negotiated pricing or credits with a provider.
* You want to use a model tier or region not available on our shared keys.
* Your compliance policy requires that API keys stay under your control.

## Quick start

Pass three headers (or SDK options) alongside your normal Dedalus API key:

| Header             | SDK option       | Description                                           |
| ------------------ | ---------------- | ----------------------------------------------------- |
| `X-Provider`       | `provider`       | Provider name (`openai`, `anthropic`, `google`, etc.) |
| `X-Provider-Key`   | `provider_key`   | Your API key for that provider                        |
| `X-Provider-Model` | `provider_model` | Model identifier at the provider (optional)           |

Only `X-Provider-Key` is strictly required. If you omit `X-Provider`, it is inferred from the model name. If you omit `X-Provider-Model`, the model from the request body is used.

## Examples

### curl

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.dedaluslabs.ai/v1/chat/completions \
  -H "Authorization: Bearer $DEDALUS_API_KEY" \
  -H "X-Provider: openai" \
  -H "X-Provider-Key: $OPENAI_API_KEY" \
  -H "X-Provider-Model: gpt-4o" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
```

### Python SDK

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from dedalus_labs import AsyncDedalus

client = AsyncDedalus(
    provider="openai",
    provider_key="sk-your-openai-key",
    provider_model="gpt-4o",
)

response = await client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
```

### TypeScript SDK

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Dedalus from "dedalus-labs";

const client = new Dedalus({
	provider: "openai",
	providerKey: "sk-your-openai-key",
	providerModel: "gpt-4o",
});

const response = await client.chat.completions.create({
	model: "openai/gpt-4o",
	messages: [{ role: "user", content: "Hello" }],
});
```

### Environment variables

You can also set BYOK options via environment variables instead of passing them in code:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export DEDALUS_PROVIDER="anthropic"
export DEDALUS_PROVIDER_KEY="sk-ant-your-key"
export DEDALUS_PROVIDER_MODEL="claude-sonnet-4-5-20250929"
```

The SDK picks these up automatically. No code changes needed.

## Per-request overrides

The SDK options set defaults for every request. You can also override per-request by setting the headers directly:

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  response = await client.chat.completions.create(
      model="google/gemini-2.5-pro",
      messages=[{"role": "user", "content": "Hello"}],
      extra_headers={
          "X-Provider": "google",
          "X-Provider-Key": "your-google-key",
      },
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await client.chat.completions.create(
  	{
  		model: "google/gemini-2.5-pro",
  		messages: [{ role: "user", content: "Hello" }],
  	},
  	{
  		headers: {
  			"X-Provider": "google",
  			"X-Provider-Key": "your-google-key",
  		},
  	},
  );
  ```
</CodeGroup>

## Supported providers

Any provider in our [model list](/sdk/guides/providers) works with BYOK:

<CardGroup cols={3}>
  <Card title="OpenAI">openai</Card>
  <Card title="Anthropic">anthropic</Card>
  <Card title="Google">google</Card>
  <Card title="xAI">xai</Card>
  <Card title="Mistral">mistral</Card>
  <Card title="DeepSeek">deepseek</Card>
  <Card title="Groq">groq</Card>
  <Card title="Cohere">cohere</Card>
  <Card title="Perplexity">perplexity</Card>
  <Card title="Cerebras">cerebras</Card>
  <Card title="Together AI">together\_ai</Card>
  <Card title="Fireworks AI">fireworks\_ai</Card>
  <Card title="Moonshot">moonshot</Card>
</CardGroup>

## How it works

Your request still goes through Dedalus. We handle routing, format normalization, streaming, and tool calling. The only difference is which API key is used for the upstream LLM call.

```
You → Dedalus API (your Dedalus key) → Provider (your provider key) → Response → You
```

<Warning>
  BYOK keys are sent over HTTPS and are never stored. They are used for the duration of the request
  and discarded. If you need Dedalus to manage keys on your behalf, contact us at
  [support@dedaluslabs.ai](mailto:support@dedaluslabs.ai).
</Warning>

## Error handling

| Scenario                        | What happens                                       |
| ------------------------------- | -------------------------------------------------- |
| Invalid provider name           | HTTP 400 with supported provider list              |
| Missing or invalid provider key | Provider returns its own auth error (usually 401)  |
| Model not available on provider | Provider returns its own model error (usually 404) |

The error response always includes the upstream provider's error message so you can debug directly.