---

name: ai-auth-helper description: Add AI model authentication to any project. Supports GitHub Copilot, Anthropic, OpenAI, OpenRouter, AWS Bedrock, Google Vertex, Cloudflare, and 50+ OpenAI-compatible providers. Uses OpenCode's proven 5-tier auth priority system (env vars, stored credentials, config files, OAuth plugins, public keys). Enables users to leverage their existing paid services without new API keys.

AI Auth Helper

Add comprehensive AI model authentication to your project using OpenCode's proven 5-tier system. Supports 75+ providers including GitHub Copilot, Anthropic, OpenAI, OpenRouter, AWS Bedrock, Google Vertex, and Cloudflare AI Gateway.

Implementation Approaches

Choose based on project needs:

Quick Setup (Environment Variables Only) - Add env var checks for target providers. See providers.md for specific variables.

Full System (Recommended) - Implement 5-tier priority: plugin OAuth → env vars → stored credentials → config files → public keys. See implementation.md for complete patterns.

Hybrid Approach - Start with env vars, progressively add credential storage and plugins as needed.

Common Workflows

Adding GitHub Copilot Authentication

Enable access to GitHub's models (o1, 4o, 4.5-sonnet) without premium credits.

Environment variable approach:

Copyif (process.env.GITHUB_TOKEN) {
  return createOpenaiCompatible({
    apiKey: process.env.GITHUB_TOKEN,
    baseURL: "https://api.githubcopilot.com"
  })
}

Full system with OAuth:

Copyconst auth = await getAuth("github-copilot", ["GITHUB_TOKEN"])
const provider = createOpenaiCompatible({
  apiKey: auth.apiKey,
  baseURL: "https://api.githubcopilot.com"
})

See providers.md → GitHub Copilot for complete implementation including OAuth plugin support.

Adding Multiple Provider Support

Step 1: Implement credential storage

• Follow implementation.md → Credential Storage

Step 2: Add provider discovery

• Fetch from https://models.dev/api.json
• Cache locally for offline use
• See implementation.md → Provider Discovery

Step 3: Implement auth priority system

• Follow implementation.md → 5-Tier Authentication System

Step 4: Add specific providers

• Check providers.md for each target provider
• Most use OpenAI-compatible pattern

Adding OpenAI-Compatible Provider

Used by 50+ providers (xAI, Groq, Together AI, Perplexity, etc.)

Pattern:

Copyimport { createOpenaiCompatible } from "@ai-sdk/openai-compatible"

// Get provider config from models.dev
const config = providers[providerID]

// Get authentication
const auth = await getAuth(providerID, config.env)

// Create provider
const provider = createOpenaiCompatible({
  apiKey: auth.apiKey,
  baseURL: config.api,
  headers: {
    ...config.headers,
    "HTTP-Referer": "https://your-app.com/",
    "X-Title": "Your App"
  }
})

See providers.md → OpenAI-Compatible Providers for details.

Adding OAuth Support

For complex flows with token refresh (GitHub Copilot, Anthropic).

Plugin loading:

Copyconst plugin = await loadPlugin("opencode-copilot-auth@0.0.9")
const method = plugin.auth.methods[0]
const result = await method.authorize({})
const callback = await result.callback()

await setCredential("github-copilot", {
  type: "oauth",
  access: callback.access_token,
  refresh: callback.refresh_token,
  expires: Date.now() + callback.expires_in * 1000
})

See implementation.md → Plugin System for complete implementation.

Supporting Corporate/Self-Hosted Deployments

Use well-known authentication for custom auth flows.

Server exposes: https://server/.well-known/opencode

Client flow:

1. Fetch well-known endpoint
2. Execute auth command from response
3. Store token with provider config
4. Use automatically

See implementation.md → Well-Known Authentication for complete implementation.

Quick Reference

Priority Order

1. Plugin OAuth (complex flows, auto-refresh)
2. Environment variables (production, CI/CD)
3. Stored credentials (~/.your-app/auth.json)
4. Config files (project-specific)
5. Public keys (free tiers)

Common Environment Variables

• GITHUB_TOKEN - GitHub Copilot
• ANTHROPIC_API_KEY - Anthropic Claude
• OPENAI_API_KEY - OpenAI
• OPENROUTER_API_KEY - OpenRouter
• GOOGLE_GENERATIVE_AI_API_KEY - Google Gemini
• GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION - Vertex AI
• AWS_REGION or AWS_BEARER_TOKEN_BEDROCK - AWS Bedrock
• CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_GATEWAY_ID - Cloudflare

Credential Storage Location

• Linux/Mac: ~/.local/share/your-app/auth.json
• Windows: ~/AppData/Local/your-app/auth.json
• Permissions: 0o600 (owner read/write only)

Provider Discovery

• API: https://models.dev/api.json
• Cache: ~/.local/share/your-app/cache/models.json
• Contains 75+ providers with models, APIs, env vars

Resources

References

• providers.md - Provider-specific authentication details for GitHub Copilot, Anthropic, OpenAI, OpenRouter, Google (Gemini & Vertex), AWS Bedrock, Cloudflare, OpenCode free models, and 50+ OpenAI-compatible providers. Start here when adding specific provider support.

• implementation.md - Complete implementation patterns: 5-tier auth system, credential storage, provider discovery, plugin OAuth flows, and well-known authentication. Use for full system implementation.

Notes

• Most providers (70%) use OpenAI-compatible pattern
• Free tier models available via OpenCode (no auth required)
• OAuth plugins available for GitHub Copilot and Anthropic
• Token refresh handled automatically by plugin loaders
• Security: Always use HTTPS, validate inputs, set file permissions to 0o600