Vercel AI Gateway OIDC Authentication in Workflow DevKit

Problem

When using the Vercel AI SDK with Workflow DevKit and vercel dev, OIDC authentication fails with:

GatewayAuthenticationError: Unauthenticated request to AI Gateway.

To authenticate, set the AI_GATEWAY_API_KEY environment variable with your API key.

This happens even when:

• Project is linked with vercel link
• OIDC token exists in .env.local via vercel env pull
• Running with vercel dev (which should auto-refresh tokens)

Root Cause

The 'use workflow' directive runs code in a sandboxed VM that does NOT have access to process.env.

The authentication flow:

1. AI SDK's generateText() calls getGatewayAuthToken()
2. This function checks process.env.AI_GATEWAY_API_KEY and process.env.VERCEL_OIDC_TOKEN
3. Inside the workflow VM, process.env is not accessible
4. Authentication fails before the fetch even happens

Solution

Use "use step" functions for AI SDK calls. Step functions have full Node.js runtime access.

Before (Broken)

import { generateText } from 'ai';
import { fetch } from 'workflow';

export async function myWorkflow(input: string) {
  'use workflow';

  // This approach doesn't work - auth happens in the sandboxed VM
  globalThis.fetch = fetch as typeof globalThis.fetch;

  const { text } = await generateText({
    model: 'openai/o4-mini',
    prompt: input,
  });
}

After (Working)

import { generateText } from 'ai';

// Step function has full Node.js access including process.env
async function generateWithAI(prompt: string) {
  'use step';
  const { text } = await generateText({
    model: 'openai/o4-mini',
    prompt,
  });
  return text;
}

export async function myWorkflow(input: string) {
  'use workflow';

  // Call the step function - auth works because step has env access
  const result = await generateWithAI(input);
}

Key Insight

Context	process.env Access	Use For
'use workflow'	❌ Sandboxed VM	Orchestration logic
'use step'	✅ Full Node.js	Side effects, API calls

Alternative: Use API Key

For simpler local development, you can use an API key instead of OIDC:

1. Go to Vercel AI Gateway API Keys
2. Create a new key
3. Add to .env.local:

   AI_GATEWAY_API_KEY=your_key_here
   

This works because the API key is read at runtime, and even in the sandboxed VM, explicit configuration can be passed to the gateway provider.

References

• Vercel AI Gateway Authentication
• AI SDK Gateway Provider
• Vercel OIDC Documentation

---

Discovered: January 26, 2026 Packages: [email protected], @ai-sdk/[email protected], [email protected]