Skip to content
Docs

AI Gateway Authentication and BYOK

Every request to AI Gateway requires Vercel authentication. Use an AI Gateway API key or OpenID Connect (OIDC) token. Bring Your Own Key (BYOK) provider credentials control how AI Gateway authenticates to a model provider, but they don't replace request authentication.

Quick start

Get authenticated in under a minute:

  1. Go to the AI Gateway API Keys page in your Vercel dashboard
  2. Click Create key and follow the steps to generate a new API key.
  3. Copy the API key and add it to your environment:
export AI_GATEWAY_API_KEY="your_api_key_here"

The AI SDK automatically uses this environment variable for authentication. If you are using a different SDK, you may need to pass the API key manually.

Authentication methods

API keys

API keys work anywhere, whether it's local development, external servers, or CI pipelines. They never expire unless you revoke them. To create, view, or delete keys, see API keys. To cap how much a key can spend, see Budgets.

When a team member leaves your team, Vercel deactivates any API keys they created. If you need authentication that isn't tied to a specific person, use OIDC tokens on Vercel deployments.

When you specify a model id as a plain string, the AI SDK automatically uses the Vercel AI Gateway provider and reads the API key from the AI_GATEWAY_API_KEY environment variable:

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

See the AI SDK authentication reference for SDK configuration and usage.

authentication.ts
import { generateText } from 'ai';
 
const { text } = await generateText({
  model: "anthropic/claude-sonnet-5",
  prompt: "Why is the sky blue?",
});
 
console.log(text);
authentication_ai.py
import asyncio
import ai
 
async def main():
    model = ai.get_model("anthropic/claude-sonnet-5")
    messages = [ai.user_message("Why is the sky blue?")]
    async with ai.stream(model, messages) as stream:
        async for event in stream:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end="", flush=True)
    print()
 
asyncio.run(main())
authentication-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": "Why is the sky blue?" }],
});
 
console.log(response.choices[0]?.message.content);
authentication_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": "Why is the sky blue?"}],
)
 
print(response.choices[0].message.content)
authentication-chat.sh
curl --fail-with-body https://ai-gateway.vercel.sh/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "anthropic/claude-sonnet-5",
  "messages": [
    {
      "role": "user",
      "content": "Why is the sky blue?"
    }
  ]
}'
authentication-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": "Why is the sky blue?" }],
  max_tokens: 1024,
});
 
for (const block of response.content) {
  if (block.type === 'text') console.log(block.text);
}
authentication_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": "Why is the sky blue?"}],
    max_tokens=1024,
)
 
for block in response.content:
    if block.type == "text":
        print(block.text)
authentication-messages.sh
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" \
  -d '{
  "model": "anthropic/claude-sonnet-5",
  "messages": [
    {
      "role": "user",
      "content": "Why is the sky blue?"
    }
  ],
  "max_tokens": 1024
}'
authentication-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: "Why is the sky blue?",
});
 
console.log(response.output_text);
authentication_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="Why is the sky blue?",
)
 
print(response.output_text)
authentication-responses.sh
curl --fail-with-body https://ai-gateway.vercel.sh/v1/responses \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "anthropic/claude-sonnet-5",
  "input": "Why is the sky blue?"
}'

OIDC tokens

Vercel deployments receive an OIDC token as VERCEL_OIDC_TOKEN, so you can authenticate without creating an API key. See OIDC for setup.

// An explicit API key takes precedence over the OIDC token.
const apiKey = process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN;

Bring Your Own Key (BYOK)

BYOK lets you use your own provider credentials. This is useful when you:

  • Have existing agreements: Use enterprise pricing or credits from providers
  • Need zero markup: BYOK requests have no additional fee
  • Require private access: Access provider features that need your own credentials
  • Want automatic fallback: If your credentials fail, requests can retry with system credentials

BYOK credentials are configured at the team level and work across all projects. See the BYOK documentation for setup instructions.

Next steps

Last updated September 8, 2026
Previous
Rate Limits
Next
API Keys

Was this helpful?

supported.