auth

Manage provider credentials and login

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

---

login

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:

1. Select provider from the list
2. Enter API key when prompted
3. 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:

1. Bearer token (AWS_BEARER_TOKEN_BEDROCK or /connect)
2. 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

1. Shows list of authenticated providers
2. Select provider to remove
3. 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:

1. Environment variables (PROVIDER_API_KEY)
2. Project .env file
3. 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:

1. models.dev - Central provider registry
2. Plugins - Providers registered by installed plugins
3. 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:

1. Select provider
2. Browser opens to authorization page
3. Grant permissions
4. Tokens saved automatically

Manual Code Flow

For providers requiring manual code entry:

1. Select provider
2. Open authorization URL
3. Copy authorization code
4. Paste code when prompted
5. 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:

1. Plugin’s authentication flow executes
2. May open browser, prompt for input, or use other methods
3. 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

Related Commands

models

List available models from providers

Providers

Learn about provider configuration

Configuration

Configure provider settings

Plugins

Custom authentication via plugins