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:

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

Full system with OAuth:

const 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:

import { 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:

const 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:

Fetch well-known endpoint
Execute auth command from response
Store token with provider config
Use automatically

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

Quick Reference

Priority Order

Plugin OAuth (complex flows, auto-refresh)
Environment variables (production, CI/CD)
Stored credentials (~/.your-app/auth.json)
Config files (project-specific)
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

ai-auth-helper