auth - OpenCode

Overview

The auth command manages authentication credentials for AI model providers. OpenCode uses models.dev provider list, allowing you to use API keys from any supported provider. Credentials are stored in ~/.local/share/opencode/auth.json and loaded automatically when OpenCode starts.

Usage

opencode auth [command]

Subcommands

login

Add credentials for a provider

list

Show all authenticated providers

logout

Remove credentials for a provider

Authenticate with a provider by storing API credentials.

Usage

opencode auth login [url]

Interactive Flow

When run without arguments, the command guides you through authentication:

Select provider from the list
Enter API key when prompted
Credentials saved to auth file

opencode auth login

Example interaction:

◆ Select provider
│ ● Anthropic (Claude Max or API key)
│   OpenAI (ChatGPT Plus/Pro or API key)
│   Google
│   OpenRouter
│   GitHub Copilot
│   Other
└ 

◆ Enter your API key
│ sk-ant-...
└ 

✓ Done

Provider-Specific Instructions

OpenCode

Recommended for best experience:

opencode auth login
# Select: OpenCode
# Get API key: https://opencode.ai/auth

Anthropic

For Claude models:

opencode auth login
# Select: Anthropic
# Get API key: https://console.anthropic.com/

OpenAI

For GPT models:

opencode auth login
# Select: OpenAI
# Get API key: https://platform.openai.com/api-keys

GitHub Copilot

Use your Copilot subscription:

opencode auth login
# Select: GitHub Copilot
# Follow OAuth flow

Amazon Bedrock

Bedrock uses AWS credential chain:

opencode auth login
# Select: Amazon Bedrock
# Configure via AWS CLI or environment variables

Authentication priority:

Bearer token (AWS_BEARER_TOKEN_BEDROCK or /connect)
AWS credential chain (profile, access keys, IAM roles)

Configure in opencode.json:

{
  "provider": {
    "amazon-bedrock": {
      "profile": "default",
      "region": "us-east-1",
      "endpoint": "https://bedrock-runtime.us-east-1.amazonaws.com"
    }
  }
}

Vercel AI Gateway

opencode auth login
# Select: Vercel
# Get API key: https://vercel.link/ai-gateway-token

Custom Providers

For providers not in the default list:

opencode auth login
# Select: Other
# Enter provider ID (lowercase, hyphens only)
# Enter API key

Then configure the provider in opencode.json. See provider documentation for details.

URL-Based Authentication

For custom authentication servers:

opencode auth login https://custom-provider.com

The provider must expose /.well-known/opencode with authentication information.

list

Display all authenticated providers.

Usage

opencode auth list

Alias:

opencode auth ls

Example Output

Credentials ~/.local/share/opencode/auth.json

◇ Anthropic (api)
◇ OpenAI (api)
◇ GitHub Copilot (oauth)
◇ OpenCode (api)

4 credentials

If environment variables are set, they’re also shown:

Environment

◇ Google (GOOGLE_GENERATIVE_AI_API_KEY)
◇ OpenRouter (OPENROUTER_API_KEY)

2 environment variables

Authentication Types

The command shows the authentication method:

api: API key authentication
oauth: OAuth-based authentication
wellknown: Custom authentication endpoint

logout

Remove stored credentials for a provider.

Usage

opencode auth logout

Interactive Flow

Shows list of authenticated providers
Select provider to remove
Credentials deleted from auth file

opencode auth logout

Example:

◆ Select provider
│ ● Anthropic (api)
│   OpenAI (api)
│   GitHub Copilot (oauth)
└ 

✓ Logout successful

Credential Storage

Credentials are stored in:

~/.local/share/opencode/auth.json

Format:

{
  "anthropic": {
    "type": "api",
    "key": "sk-ant-..."
  },
  "openai": {
    "type": "api",
    "key": "sk-..."
  },
  "github-copilot": {
    "type": "oauth",
    "access": "...",
    "refresh": "...",
    "expires": 1234567890
  }
}

Keep your auth.json file secure. It contains sensitive API keys.

Environment Variables

You can also provide credentials via environment variables:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_GENERATIVE_AI_API_KEY="..."

Or in a .env file in your project:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

Environment variables take precedence over stored credentials.

Authentication Priority

OpenCode loads credentials in this order:

Environment variables (PROVIDER_API_KEY)
Project .env file
Stored credentials (~/.local/share/opencode/auth.json)

Higher priority sources override lower ones.

Provider Discovery

When you run opencode auth login, the list of providers comes from:

models.dev - Central provider registry
Plugins - Providers registered by installed plugins
Custom config - Providers defined in opencode.json

Disable providers in configuration:

{
  "disabled_providers": ["openrouter", "together"]
}

Or enable only specific providers:

{
  "enabled_providers": ["anthropic", "openai", "opencode"]
}

OAuth Authentication

Some providers use OAuth instead of API keys:

Automatic Flow

For providers with automatic OAuth:

Select provider
Browser opens to authorization page
Grant permissions
Tokens saved automatically

Manual Code Flow

For providers requiring manual code entry:

Select provider
Open authorization URL
Copy authorization code
Paste code when prompted
Tokens saved

Token Refresh

OpenCode automatically refreshes OAuth tokens before they expire. If refresh fails:

# Re-authenticate
opencode auth logout
opencode auth login

Plugin Authentication

Plugins can register custom authentication methods. When you select a plugin-registered provider:

Plugin’s authentication flow executes
May open browser, prompt for input, or use other methods
Credentials saved to auth file

See plugin documentation for creating custom authentication.

Security Best Practices

Use environment variables

For CI/CD and automated environments

Rotate keys regularly

Update API keys periodically

Limit key permissions

Use least-privilege API keys when possible

Don't commit credentials

Add .env and auth.json to .gitignore

Troubleshooting

Authentication Failed

Problem: Invalid API key error Solutions:

Verify key is correct (copy/paste carefully)
Check key has proper permissions
Ensure key hasn’t expired
Try generating a new key

Provider Not Listed

Problem: Can’t find provider in list Solutions:

Run opencode models --refresh to update provider list
Select “Other” and enter provider ID manually
Check provider is supported on models.dev
Configure custom provider in opencode.json

OAuth Failed

Problem: OAuth authorization fails Solutions:

Try again (tokens may have expired)
Clear browser cookies for the provider
Check internet connectivity
Verify the provider supports OAuth

Environment Variables Not Working

Problem: Environment variables not recognized Solutions:

Check variable name matches provider convention
Verify variables are exported: export VARIABLE=value
Confirm .env file is in project root
Run opencode auth list to see detected variables

models

List available models from providers

Providers

Learn about provider configuration

Configuration

Configure provider settings

Plugins

Custom authentication via plugins

Commands

In-Session Commands

Documentation Index

​Overview

​Usage

​Subcommands

login

list

logout

​login

​Usage

​Interactive Flow

​Provider-Specific Instructions

​OpenCode

​Anthropic

​OpenAI

​GitHub Copilot

​Amazon Bedrock

​Vercel AI Gateway

​Custom Providers

​URL-Based Authentication

​list

​Usage

​Example Output

​Authentication Types

​logout

​Usage

​Interactive Flow

​Credential Storage

​Environment Variables

​Authentication Priority

​Provider Discovery

​OAuth Authentication

​Automatic Flow

​Manual Code Flow

​Token Refresh

​Plugin Authentication

​Security Best Practices

Use environment variables

Rotate keys regularly

Limit key permissions

Don't commit credentials

​Troubleshooting

​Authentication Failed

​Provider Not Listed

​OAuth Failed

​Environment Variables Not Working

​Related Commands

models

Providers

Configuration

Plugins

Build docs developers (and LLMs) love

Overview

Usage

Subcommands

login

Usage

Interactive Flow

Provider-Specific Instructions

OpenCode

Anthropic

OpenAI

GitHub Copilot

Amazon Bedrock

Vercel AI Gateway

Custom Providers

URL-Based Authentication

list

Usage

Example Output

Authentication Types

logout

Usage

Interactive Flow

Credential Storage

Environment Variables

Authentication Priority

Provider Discovery

OAuth Authentication

Automatic Flow

Manual Code Flow

Token Refresh

Plugin Authentication

Security Best Practices

Troubleshooting

Authentication Failed

Provider Not Listed

OAuth Failed

Environment Variables Not Working

Related Commands