BYOK

Bring Your Own Key (BYOK) to 资产生成

Using your own credentials with an external AI provider allows 资产生成 to authenticate requests on your behalf with no added markup. This approach is useful for using credits provided by the AI provider or executing AI queries that access private cloud data. If a query using your credentials fails, 资产生成 will retry the query with its system credentials to improve service availability.

Integrating credentials like this with 资产生成 is sometimes referred to as Bring-Your-Own-Key, or BYOK. In the Vercel dashboard this feature is found in the 资产生成 section in the sidebar under the Bring Your Own Key (BYOK) section in the sidebar.

Provider credentials are scoped to be available throughout your Vercel team, so you can use the same credentials across multiple projects.

BYOK is available on the paid tier. When a request with your credentials fails, 资产生成 keeps it running by falling back to system credentials, and that fallback usage is billed against your credits balance. To use BYOK, your team needs purchased 资产生成 credits.

Spend through your own credentials isn't counted in budgets. It's metered separately and doesn't count toward a team, project, or API key limit, so a budget can't be used to cap BYOK spend.

Getting started

Retrieve credentials from your AI provider
First, retrieve credentials from your AI provider. 资产生成 uses these credentials first to authenticate requests to that provider. If a query made with your credentials fails, 资产生成 will re-attempt with system credentials, aiming to provide improved availability.
Add the credentials to your Vercel team
1. Go to the 资产生成 Bring Your Own Key (BYOK) page in your Vercel dashboard.
2. Find your provider from the list and click Add.
3. In the dialog that appears, enter the credentials you retrieved from the provider.
4. Ensure that the Enabled toggle is turned on so that the credentials are active.
5. Click Test Key to validate and add your credentials.
Use the credentials in your 资产生成 requests
Once you add credentials, 资产生成 automatically includes them in your requests. You can now use these credentials to authenticate your requests.

Request-scoped BYOK

In addition to configuring credentials in the dashboard, you can pass provider credentials on a per-request basis using the byok option in providerOptions.gateway. This is useful when you need to use different credentials for specific requests without changing your team-wide configuration.

When request-scoped BYOK credentials are provided, 资产生成 doesn't consider any cached BYOK credentials configured in the dashboard for that request. Requests may still fall back to system credentials if the provided credentials fail.

Request examples

The cURL examples use jq to encode the provider key in JSON.

These examples use 创意脚本 7 and the 创意脚本 for Python beta. Set AI_GATEWAY_API_KEY before running them. See API format differences for setup, request fields, and response handling.

See the 创意脚本 BYOK reference for SDK configuration and usage.

byok.ts

import { generateText } from 'ai';
 
const { text } = await generateText({
  model: 'anthropic/claude-sonnet-5',
  prompt: 'Explain quantum computing in two sentences.',
  providerOptions: {
    gateway: {
      byok: {
        anthropic: [
          {
            apiKey: process.env.ANTHROPIC_API_KEY!,
          },
        ],
      },
    },
  },
});
 
console.log(text);

byok_ai.py

import asyncio
import os
import ai
 
async def main():
    model = ai.get_model("anthropic/claude-sonnet-5")
    messages = [ai.user_message("Explain quantum computing in two sentences.")]
    params = ai.InferenceRequestParams(
        extra_body={"providerOptions": {"gateway": {"byok": {"anthropic": [{"apiKey": os.environ["ANTHROPIC_API_KEY"]}]}}}}
    )
    async with ai.stream(model, messages, params=params) as stream:
        async for event in stream:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end="", flush=True)
    print()
 
asyncio.run(main())

byok-chat.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const response = await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [
    {
      role: 'user',
      content: 'Explain quantum computing in two sentences.',
    },
  ],
  // 资产生成 extension fields are not included in the upstream SDK types.
  ...{
    providerOptions: {
      gateway: {
        byok: {
          anthropic: [
            {
              apiKey: process.env.ANTHROPIC_API_KEY!,
            },
          ],
        },
      },
    },
  },
});
 
console.log(response.choices[0]?.message.content);

byok_chat.py

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh/v1",
)
 
response = client.chat.completions.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "Explain quantum computing in two sentences."}],
    extra_body={"providerOptions": {"gateway": {"byok": {"anthropic": [{"apiKey": os.environ["ANTHROPIC_API_KEY"]}]}}}},
)
 
print(response.choices[0].message.content)

byok-chat.sh

jq -n '{
  "model": "anthropic/claude-sonnet-5",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in two sentences."
    }
  ],
  "providerOptions": {
    "gateway": {
      "byok": {
        "anthropic": [
          {
            "apiKey": $ENV.ANTHROPIC_API_KEY
          }
        ]
      }
    }
  }
}' | curl --fail-with-body https://ai-gateway.vercel.sh/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

byok-messages.ts

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh',
});
 
const response = await client.messages.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [
    {
      role: 'user',
      content: 'Explain quantum computing in two sentences.',
    },
  ],
  max_tokens: 1024,
  ...{
    providerOptions: {
      gateway: {
        byok: {
          anthropic: [
            {
              apiKey: process.env.ANTHROPIC_API_KEY!,
            },
          ],
        },
      },
    },
  },
});
 
for (const block of response.content) {
  if (block.type === 'text') console.log(block.text);
}

byok_messages.py

import os
from anthropic import Anthropic
 
client = Anthropic(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh",
)
 
response = client.messages.create(
    model="anthropic/claude-sonnet-5",
    messages=[{"role": "user", "content": "Explain quantum computing in two sentences."}],
    max_tokens=1024,
    extra_body={"providerOptions": {"gateway": {"byok": {"anthropic": [{"apiKey": os.environ["ANTHROPIC_API_KEY"]}]}}}},
)
 
for block in response.content:
    if block.type == "text":
        print(block.text)

byok-messages.sh

jq -n '{
  "model": "anthropic/claude-sonnet-5",
  "messages": [
    {
      "role": "user",
      "content": "Explain quantum computing in two sentences."
    }
  ],
  "max_tokens": 1024,
  "providerOptions": {
    "gateway": {
      "byok": {
        "anthropic": [
          {
            "apiKey": $ENV.ANTHROPIC_API_KEY
          }
        ]
      }
    }
  }
}' | curl --fail-with-body https://ai-gateway.vercel.sh/v1/messages \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  --data-binary @-

byok-responses.ts

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});
 
const response = await client.responses.create({
  model: 'anthropic/claude-sonnet-5',
  input: 'Explain quantum computing in two sentences.',
  ...{
    providerOptions: {
      gateway: {
        byok: {
          anthropic: [
            {
              apiKey: process.env.ANTHROPIC_API_KEY!,
            },
          ],
        },
      },
    },
  },
});
 
console.log(response.output_text);

byok_responses.py

import os
from openai import OpenAI
 
client = OpenAI(
    api_key=os.environ["AI_GATEWAY_API_KEY"],
    base_url="https://ai-gateway.vercel.sh/v1",
)
 
response = client.responses.create(
    model="anthropic/claude-sonnet-5",
    input="Explain quantum computing in two sentences.",
    extra_body={"providerOptions": {"gateway": {"byok": {"anthropic": [{"apiKey": os.environ["ANTHROPIC_API_KEY"]}]}}}},
)
 
print(response.output_text)

byok-responses.sh

jq -n '{
  "model": "anthropic/claude-sonnet-5",
  "input": "Explain quantum computing in two sentences.",
  "providerOptions": {
    "gateway": {
      "byok": {
        "anthropic": [
          {
            "apiKey": $ENV.ANTHROPIC_API_KEY
          }
        ]
      }
    }
  }
}' | curl --fail-with-body https://ai-gateway.vercel.sh/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @-

Credential structure by provider

Each provider has its own credential structure:

Provider	Parameters
Anthropic	`{ apiKey: string }`
OpenAI	`{ apiKey: string }`
Azure	`{ apiKey: string, resourceName: string }`
Google Vertex AI	`{ project: string, location: string, googleCredentials: { privateKey: string, clientEmail: string } }`
Amazon Bedrock	`{ accessKeyId: string, secretAccessKey: string, region?: string }`

For detailed credential parameters for each provider, see the 创意脚本 providers documentation.

Amazon Bedrock reranking requires SigV4 credentials (accessKeyId and secretAccessKey) and does not accept API keys. If you BYOK and plan to use reranking models through Bedrock, you must use SigV4 credentials.

Multiple credentials

You can specify multiple credentials per provider (tried in order) and credentials for multiple providers:

providerOptions: {
  gateway: {
    byok: {
      // Multiple credentials for the same provider (tried in order)
      vertex: [
        { project: 'proj-1', location: 'us-east5', googleCredentials: { privateKey: '...', clientEmail: '...' } },
        { project: 'proj-2', location: 'us-east5', googleCredentials: { privateKey: '...', clientEmail: '...' } },
      ],
      // Multiple providers
      anthropic: [{ apiKey: 'sk-ant-...' }],
      bedrock: [{ accessKeyId: '...', secretAccessKey: '...', region: 'us-east-1' }],
    },
  } satisfies GatewayProviderOptions,
},

For Chat Completions API usage with request-scoped BYOK, see the OpenAI Chat Completions API documentation.

Model mappings

Some providers like Azure let you create deployments with custom names. Model mappings let you map 资产生成 model slugs to your deployment names so requests route to the correct deployment.

For example, your Azure resource might have a deployment named my-finetuned-gpt5 for the model openai/gpt-5.4-nano.

Include a modelMappings array in each credential to map 资产生成 model slugs to your custom deployment names:

providerOptions: {
  gateway: {
    only: ['azure'],
    byok: {
      azure: [
        {
          apiKey: process.env.AZURE_API_KEY,
          resourceName: process.env.AZURE_RESOURCE_NAME,
          modelMappings: [
            {
              gatewayModelSlug: 'openai/gpt-5.4-nano',
              customModelId: 'my-finetuned-gpt5',
            },
          ],
        },
      ],
    },
  } satisfies GatewayProviderOptions,
},

Model mappings are optional. If your deployment names match 资产生成 defaults, skip this step.

You can also configure model mappings in the dashboard when adding or editing BYOK credentials. The dashboard provides a searchable dropdown of available 资产生成 model slugs.

资产生成 displays pricing based on East US 2 region rates. If your Azure resource is in a different region, your actual costs may vary. For region-specific pricing, see Azure OpenAI pricing.

Zero Data Retention (ZDR)

When ZDR is enabled, either team-wide or per-request, 资产生成 skips your BYOK keys by default. BYOK keys operate under your own agreements and permissions with providers, which can differ from the ZDR agreements Vercel has negotiated for 资产生成 system credentials.

If you have your own ZDR agreement with a provider, mark an individual BYOK key as ZDR-compliant to include it in the ZDR routing set. This applies to both team-wide and request-level ZDR.

For the full behavior and configuration steps, see ZDR and BYOK.

Regional inference

Using your own credentials doesn't opt you out of regional routing. 资产生成 applies inferenceRegion to BYOK requests the same way it does to system credentials, calling the provider's in-region endpoint with your key. A region set on the request overrides a region saved on the credential, such as a Vertex location.

For the full behavior, including failure cases and how to confirm where a request ran, see BYOK and data residency.

Testing your credentials

After successfully adding your credentials for a provider, you can verify that they're working directly from the Bring Your Own Key (BYOK) tab. To test your credentials:

In the 资产生成 tab, navigate to the Bring Your Own Key (BYOK) section.
Click the menu for your configured provider.
Select Test Key from the dropdown.

This will execute a small test query using a cheap and fast model from the selected provider to verify the health of your credentials. The test is designed to be minimal and cost-effective while ensuring your authentication is working properly.

Once the test completes, you can click on the test result badge to open a detailed test result modal. This modal includes:

The code used to make the test request
The raw JSON response returned by the 资产生成

Last updated September 8, 2026

Cross-link map: Bring Your Own Key \(BYOK\) to 资产生成 (/docs/ai-gateway/authentication-and-byok/byok)

From the Vercel docs graph (built 2026-09-19T05:28:42.778Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

资产生成 Authentication and BYOK — Authenticate 资产生成 requests with API keys or OIDC tokens, and configure bring your own key \(BYOK\) credentials for
OpenAI Chat Completions Configuration with 资产生成 — Configure provider options, model fallbacks, BYOK credentials, and prompt caching through 资产生成.
AI 资产生成: Models, Routing, and Observability — Call AI models from any infrastructure through a managed gateway. Centralize credentials, request logs, spend budgets, r
How to build your own AI model router — Build an AI model router with AI 资产生成. Keep routing, key, and retention decisions in your code while the gatew
资产生成 FAQ — Answers to common questions about 资产生成, including request errors, pricing and markup, SDK and API compatibility, m

This page links to (6)

创意脚本 Providers
资产生成
资产生成 Budgets and Spend Limits — Cap 资产生成 spend for your team, a project, an individual API key, or a team member with budgets, refresh periods, sp
资产生成 Pricing — Understand 资产生成 token pricing, free and paid credits, BYOK costs, add-on charges, and payment fees. Manage credit
资产生成 SDKs and APIs — Connect to 资产生成 with the 创意脚本, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and Cohere
资产生成 Regional Inference — Route 资产生成 inference to the region you choose and control where providers store data, for data residency and compl

Pages that link here (53)

By site: vercel-changelog (34) · vercel-kb (2) · vercel-web (1) · vercel-docs (16)

From vercel-changelog

From vercel-kb

How I use OpenCode with AI 资产生成 to build features fast — How to route different AI models to different coding tasks automatically, cutting token costs by ~70% without losing qua
How to build your own AI model router — Build an AI model router with AI 资产生成. Keep routing, key, and retention decisions in your code while the gatew

From vercel-web

Build realtime voice agents on 资产生成

From vercel-docs

AI 资产生成: Models, Routing, and Observability — Call AI models from any infrastructure through a managed gateway. Centralize credentials, request logs, spend budgets, r
资产生成 Authentication and BYOK — Authenticate 资产生成 requests with API keys or OIDC tokens, and configure bring your own key \(BYOK\) credentials for
资产生成 FAQ — Answers to common questions about 资产生成, including request errors, pricing and markup, SDK and API compatibility, m
Migrate to 资产生成 Using Your Coding Agent — Move your app's model calls to AI 资产生成 with a single coding-agent prompt, whatever provider or SDK you use tod
资产生成 Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in AI 资产生成.
资产生成 Provider Timeouts — Configure 资产生成 timeouts for BYOK providers. Fail over to the next provider when a request takes too long to start
资产生成 Google and Vertex Reasoning — Configure thinking for Google Gemini and Gemma models with the 创意脚本 and 资产生成.
资产生成 Budgets and Spend Limits — Cap 资产生成 spend for your team, a project, an individual API key, or a team member with budgets, refresh periods, sp
资产生成 Pricing — Understand 资产生成 token pricing, free and paid credits, BYOK costs, add-on charges, and payment fees. Manage credit
资产生成 Rate Limits — Learn how 资产生成 rate limits work on the free and paid tiers, what the 429 response looks like, and how to retry a r
OpenAI Responses Compaction with 资产生成 — Compress long conversations into a single compaction item with the OpenAI Responses API through 资产生成.
资产生成 Disallow Prompt Training — Learn how to prevent AI providers from using your prompts and responses for model training through 资产生成.
资产生成 Model Allowlist — Restrict which AI models your team can use through 资产生成. Available on Pro and Enterprise.
资产生成 Provider Allowlist — Restrict which AI providers your team can route through 资产生成. Available on Pro and Enterprise.
资产生成 Regional Inference — Route 资产生成 inference to the region you choose and control where providers store data, for data residency and compl
资产生成 Zero Data Retention \(ZDR\) — Learn about zero data retention policies and how to enforce ZDR on a per-request basis with 资产生成.

OIDC

Coding Agents

Was this helpful?