---
title: "Bring Your Own Keys"
description: "Add a provider credential, test it, and inspect routing metadata to see whether a BYOK or system credential served the request."
canonical_url: "https://vercel.com/academy/ai-gateway/bring-your-own-keys"
md_url: "https://vercel.com/academy/ai-gateway/bring-your-own-keys.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-08-08T23:27:13.432Z"
content_type: "lesson"
course: "ai-gateway"
course_title: "Using AI Gateway in Production"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Bring Your Own Keys

# How Do I Bring My Own Provider Keys?

Bring Your Own Key, or BYOK, lets AI Gateway authenticate to model providers with credentials you already manage.

The provider bills you under your existing terms, and Vercel adds no markup or fee. BYOK is useful when you have provider credits, negotiated enterprise rates, or models deployed in your own cloud that Gateway system credentials cannot reach.

\*\*Note: Quick Answer\*\*

Add and test a provider credential in the Gateway BYOK settings. Matching traffic can use that credential, and `credentialType` in the routing metadata identifies whether `byok` or `system` credentials served each attempt. A failed BYOK attempt can fall back to system credentials and use Gateway credits.

## Outcome

Add a provider key, and prove from a response's routing metadata exactly whose credentials, yours or the system's, served the request.

## Fast Track

1. **AI Gateway** tab → **Bring Your Own Key (BYOK)** → find your provider → **Add**
2. Enter credentials, leave **Enabled** on, click **Test Key**
3. Run `pnpm whose-key` and read `credentialType` off the receipt

## Hands-on exercise

Assume Taco Tuesday already has provider credits with Anthropic. Adding that credential lets matching requests use the provider account while the application keeps its Gateway request path.

Requirements:

- Add the provider key in the dashboard BYOK section and confirm **Test Key** passes
- Build `scripts/whose-key.ts`: one request to a model that provider serves, then walk `routing.modelAttempts[].providerAttempts[]` from the metadata and print each attempt's `provider`, `credentialType`, and `success`
- Update your spend policy from lesson 2.5 to include provider-side billing and fallback usage

No provider key handy? Run the script anyway. Every attempt will say `credentialType: "system"`, which is the baseline reading, and the script becomes your verification tool the day you do add one.

## Try It

```bash
pnpm whose-key
```

With a BYOK key configured for Anthropic:

```
Attempt 1: anthropic (byok) — success
Served by: anthropic using YOUR key
```

`credentialType: "byok"` confirms that the provider credential served the successful request.

The following block is a previously captured, sanitized fallback trace:

```
Attempt 1: anthropic (byok) — failed: Unauthorized
Attempt 2: anthropic (system) — success
Served by: anthropic using system credentials
```

Two issues you may encounter:

**Every attempt says `system`.** Check that the credential is enabled and that the provider serves the selected model. Use `only` or `order` from lesson 1.7 when traffic must reach the provider that owns the key.

**You're on the free tier.** BYOK requires purchased credits, precisely because of the fallback: the Gateway needs a balance to bill when it rescues your failed request with system credentials.

## Commit

```bash
git commit -m "feat(byok): add whose-key script to verify credential routing"
```

## Done-When

- [ ] Test Key passes in the dashboard (or you've consciously deferred adding a key)
- [ ] `scripts/whose-key.ts` prints `credentialType` for every attempt
- [ ] You can explain where the money goes in both the `byok` and fallback cases
- [ ] The spend policy reflects the new provider credential and fallback path

## Solution

```ts filename="scripts/whose-key.ts"
import { generateText } from "ai";

const result = await generateText({
  model: "anthropic/claude-sonnet-4.6",
  prompt: "One sentence: talk a nervous first-timer into the Birria Eclipse.",
});

const routing = result.finalStep.providerMetadata?.gateway?.routing as any;
const attempts = routing?.modelAttempts?.flatMap(
  (m: any) => m.providerAttempts ?? []
) ?? [];

attempts.forEach((a: any, i: number) => {
  const outcome = a.success ? "success" : `failed: ${a.error}`;
  console.log(`Attempt ${i + 1}: ${a.provider} (${a.credentialType}) — ${outcome}`);
});

const winner = attempts.find((a: any) => a.success);
const whose = winner?.credentialType === "byok" ? "YOUR key" : "system credentials";
console.log(`Served by: ${winner?.provider} using ${whose}`);
```

For per-request credentials instead of team-wide ones, the same proof works with the request-scoped option:

```ts
providerOptions: {
  gateway: {
    byok: {
      anthropic: [{ apiKey: process.env.ANTHROPIC_API_KEY }],
    },
  },
},
```

The routing metadata identifies the billing path for each attempt, which belongs in the spend policy from lesson 2.5.

## Related Questions

- [How do I set a budget so I don't get a surprise bill?](/ai-gateway/save-money/set-a-budget)
- [How do I pin routing to a specific provider?](/ai-gateway/stay-reliable/pin-a-provider)
- [How do I use AI credits I already bought?](/ai-gateway/save-money/use-ai-credits)


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)