Using your own credentials with an external AI provider allows AI Gateway 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, AI Gateway will retry the query with its system credentials to improve service availability.
Integrating credentials like this with AI Gateway is sometimes referred to as Bring-Your-Own-Key, or BYOK. In the Vercel dashboard this feature is found in the AI Gateway 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.
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 providerFirst, retrieve credentials from your AI provider. AI Gateway uses these credentials first to authenticate requests to that provider. If a query made with your credentials fails, AI Gateway will re-attempt with system credentials, aiming to provide improved availability.
-
Add the credentials to your Vercel team
- Go to the AI Gateway Bring Your Own Key (BYOK) page in your Vercel dashboard.
- Find your provider from the list and click Add.
- In the dialog that appears, enter the credentials you retrieved from the provider.
- Ensure that the Enabled toggle is turned on so that the credentials are active.
- Click Test Key to validate and add your credentials.
- Use the credentials in your AI Gateway requestsOnce you add credentials, AI Gateway automatically includes them in your requests. You can now use these credentials to authenticate your requests.
When request-scoped BYOK credentials are provided, AI Gateway 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.
You can reach our customer support team by emailing info@yourcompany.example.com, calling +1 555-555-5556, or using the live chat on our website. Our dedicated team is available 24/7 to assist with any inquiries or issues.
We’re committed to providing prompt and effective solutions to ensure your satisfaction.
We offer a 30-day return policy for all products. Items must be in their original condition, unused, and include the receipt or proof of purchase. Refunds are processed within 5-7 business days of receiving the returned item.
AI SDK
const { text } =awaitgenerateText({
prompt:'Explain quantum computing in two sentences.',
import { generateText } from'ai';
byok: {
model:'anthropic/claude-sonnet-5',
},
See the AI SDK BYOK reference for SDK configuration and usage.
apiKey:process.env.ANTHROPIC_API_KEY!,
providerOptions: {
anthropic: [
gateway: {
console.log(text);
},
],
});
{
},
},
Credential structure by provider
Each provider has its own credential structure:
Provider
OpenAI
Parameters
{ apiKey: string }
{ apiKey: string }
Anthropic
Azure
Amazon Bedrock
Google Vertex AI
{ accessKeyId: string, secretAccessKey: string, region?: string }
{ apiKey: string, resourceName: string }
{ project: string, location: string, googleCredentials: { privateKey: string, clientEmail: string } }
Multiple credentials
For detailed credential parameters for each provider, see the AI SDK providers documentation.
You can specify multiple credentials per provider (tried in order) and credentials for multiple providers:
providerOptions: {
gateway: {
vertex: [
],
byok: {
bedrock: [{ accessKeyId:'...', secretAccessKey:'...', region:'us-east-1' }],
// Multiple credentials for the same provider (tried in order)
{ project:'proj-1', location:'us-east5', googleCredentials: { privateKey:'...', clientEmail
},
},
// Multiple providers
} satisfiesGatewayProviderOptions,
anthropic: [{ apiKey:'sk-ant-...' }],
{ project:'proj-2', location:'us-east5', googleCredentials: { privateKey:'...', clientEmail
OpenAI Chat Completions API
documentation.
Some providers like Azure let you create deployments with custom names. Model mappings let you map AI Gateway 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 AI Gateway model slugs to your custom deployment names:
Our Services
resourceName:process.env.AZURE_RESOURCE_NAME,
byok: {
{
providerOptions: {
azure: [
apiKey:process.env.AZURE_API_KEY,
},
{
gatewayModelSlug:'openai/gpt-5.4-nano',
only: ['azure'],
gateway: {
customModelId:'my-finetuned-gpt5',
modelMappings: [
],
},
},
},
} satisfiesGatewayProviderOptions,
],
Model mappings are optional. If your deployment names match AI Gateway 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 AI Gateway model slugs.
Zero Data Retention (ZDR)
When ZDR is enabled, either team-wide or per-request, AI Gateway 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 AI Gateway 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.
Using your own credentials doesn't opt you out of regional routing. AI Gateway 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.
You can reach our customer support team by emailing info@yourcompany.example.com, calling +1 555-555-5556, or using the live chat on our website. Our dedicated team is available 24/7 to assist with any inquiries or issues.
We’re committed to providing prompt and effective solutions to ensure your satisfaction.
We offer a 30-day return policy for all products. Items must be in their original condition, unused, and include the receipt or proof of purchase. Refunds are processed within 5-7 business days of receiving the returned item.
Previous
Last updated September 8, 2026
Cross-link map: Bring Your Own Key \(BYOK\) to AI Gateway (/docs/ai-gateway/authentication-and-byok/byok)From the Vercel docs graph (built 2026-09-21T05:26:59.511Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.jsonSemantically closest pagesAI Gateway Authentication and BYOK — Authenticate AI Gateway requests with API keys or OIDC tokens, and configure bring your own key \(BYOK\) credentials forOpenAI Chat Completions Configuration with AI Gateway — Configure provider options, model fallbacks, BYOK credentials, and prompt caching through AI Gateway.Vercel AI Gateway: Models, Routing, and Observability — Call AI models from any infrastructure through a managed gateway. Centralize credentials, request logs, spend budgets, rHow to build your own AI model router — Build an AI model router with Vercel AI Gateway. Keep routing, key, and retention decisions in your code while the gatewAI Gateway FAQ — Answers to common questions about AI Gateway, including request errors, pricing and markup, SDK and API compatibility, mThis page links to (6)AI SDK ProvidersAI GatewayAI Gateway Budgets and Spend Limits — Cap AI Gateway spend for your team, a project, an individual API key, or a team member with budgets, refresh periods, spAI Gateway Pricing — Understand AI Gateway token pricing, free and paid credits, BYOK costs, add-on charges, and payment fees. Manage creditAI Gateway SDKs and APIs — Connect to AI Gateway with the AI SDK, Python, REST, or compatible OpenAI, Anthropic Messages, OpenResponses, and CohereAI Gateway Regional Inference — Route AI Gateway inference to the region you choose and control where providers store data, for data residency and complPages that link here (55)By site: vercel-changelog (34) · vercel-kb (2) · vercel-web (1) · vercel-docs (18)From vercel-changelog10x more capacity for Laguna S 2.1 on AI GatewayClaude Sonnet 5 now available on Vercel AI GatewayDeepSeek V4.1 Flash now available on AI GatewayDeepSeek V4 Flash now runs updated weights on AI GatewayDeepSeek V4 Pro now runs updated weights on AI GatewayGemini 3.6 Flash and Gemini 3.5 Flash-Lite are now available on AI GatewayGemini 3.7 Flash now available on AI Gateway for 50% offGemini 3.8 Flash now available on AI GatewayGLM 5.2 Fast via Wafer now available on AI GatewayGLM 5.3 FlashX now available on AI GatewayGLM 5.3 now available on AI GatewayGPT 5.6 Sol, Luna, and Terra now available on AI GatewayGPT-5.6 Sol is 50% off on AI Gateway for the next monthGPT-5.6 Sol is now 50% off a lower priceGrok 4.5 now available on AI GatewayGrok 4.6 now available on AI GatewayGrok Build 0.1 now available on Vercel AI GatewayHy4 Preview now available on AI GatewayInkling from Thinking Machines is now available on AI GatewayInkling Small from Thinking Machines is now available on AI GatewayKimi K3 is now available on AI GatewayLaguna S 2.1 is now available on AI GatewayLing 3.0 Flash is now available on AI GatewayLing 3.0 Tiny is now available on AI GatewayMuse Image now available on AI GatewayMuse Spark 1.1 is now available on AI GatewayMuse Spark 1.2 is now available on Vercel AI GatewayNano Banana 2 Lite (Gemini 3.1 Flash Lite Image) now on AI GatewayQwen 3.7 Max now available on Vercel AI GatewayQwen 3.8 Flash now available on AI GatewayQwen 3.8 Max now available on Vercel AI GatewaySakana Fugu Ultra now available on AI GatewaySeedream 5.0 Pro is now available on AI GatewaySet per-user budgets on AI GatewayFrom vercel-kbHow I use OpenCode with Vercel AI Gateway to build features fast — How to route different AI models to different coding tasks automatically, cutting token costs by ~70% without losing quaHow to build your own AI model router — Build an AI model router with Vercel AI Gateway. Keep routing, key, and retention decisions in your code while the gatewFrom vercel-webBuild realtime voice agents on AI GatewayFrom vercel-docsVercel AI Gateway: Models, Routing, and Observability — Call AI models from any infrastructure through a managed gateway. Centralize credentials, request logs, spend budgets, rAI Gateway Authentication and BYOK — Authenticate AI Gateway requests with API keys or OIDC tokens, and configure bring your own key \(BYOK\) credentials forAI Gateway FAQ — Answers to common questions about AI Gateway, including request errors, pricing and markup, SDK and API compatibility, mMigrate to AI Gateway Using Your Coding Agent — Move your app's model calls to Vercel AI Gateway with a single coding-agent prompt, whatever provider or SDK you use todEvaluation — Evaluate shared state against typed questions and get back structured choices, scores, and boolean probabilities throughAI Gateway Provider Routing and Fallbacks — Configure provider routing, ordering, and fallback behavior in Vercel AI Gateway.AI Gateway Provider Timeouts — Configure AI Gateway timeouts for BYOK providers. Fail over to the next provider when a request takes too long to startAI Gateway Google and Vertex Reasoning — Configure thinking for Google Gemini and Gemma models with the AI SDK and AI Gateway.AI Gateway Budgets and Spend Limits — Cap AI Gateway spend for your team, a project, an individual API key, or a team member with budgets, refresh periods, spAI Gateway Pricing — Understand AI Gateway token pricing, free and paid credits, BYOK costs, add-on charges, and payment fees. Manage creditAI Gateway Rate Limits — Learn how AI Gateway rate limits work on the free and paid tiers, what the 429 response looks like, and how to retry a rOpenAI Responses Compaction with AI Gateway — Compress long conversations into a single compaction item with the OpenAI Responses API through AI Gateway.TypeSafe API with AI Gateway — Point an existing TypeSafe client at AI Gateway by changing its base URL to route System One evaluation requests throughAI Gateway Disallow Prompt Training — Learn how to prevent AI providers from using your prompts and responses for model training through AI Gateway.AI Gateway Model Allowlist — Restrict which AI models your team can use through AI Gateway. Available on Pro and Enterprise.AI Gateway Provider Allowlist — Restrict which AI providers your team can route through AI Gateway. Available on Pro and Enterprise.AI Gateway Regional Inference — Route AI Gateway inference to the region you choose and control where providers store data, for data residency and complAI Gateway Zero Data Retention \(ZDR\) — Learn about zero data retention policies and how to enforce ZDR on a per-request basis with AI Gateway.
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.
Can you trust our partners?
OIDC
Once the test completes, you can click on the test result badge to open a detailed test result modal. This modal includes:
Was this helpful?
Coding Agents
- The code used to make the test request
- The raw JSON response returned by the AI Gateway