getcompanion-ai/co-mono
1
0
Fork 0
mirror of https://github.com/getcompanion-ai/co-mono.git synced 2026-04-15 06:04:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(coding-agent): rewrite authentication.md with proper structure

Browse source 
- Subscriptions first (OAuth providers)
- Clear API keys table
- Auth file format
- Cloud providers section (Azure, Bedrock, Vertex)
- Resolution order
- Troubleshooting
This commit is contained in:
Mario Zechner 2026-01-25 21:42:20 +01:00
parent 8d11d1e2f3
commit 726e0a4b5b
1 changed files with 101 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

160
packages/coding-agent/docs/authentication.md
View file

@ -1,6 +1,78 @@
# Authentication
Pi supports API keys (environment variables or auth file) and OAuth for subscription-based providers.
Pi supports subscription-based providers via OAuth and API key providers via environment variables or auth file.
## Table of Contents
- [Subscriptions](#subscriptions)
- [API Keys](#api-keys)
- [Auth File](#auth-file)
- [Cloud Providers](#cloud-providers)
- [Resolution Order](#resolution-order)
- [Troubleshooting](#troubleshooting)
## Subscriptions
Use `/login` in interactive mode to authenticate with your existing subscription or free tier:
| Provider | Command | Cost |
|----------|---------|------|
| Claude Pro/Max | `/login anthropic` | Subscription |
| ChatGPT Plus/Pro | `/login openai-codex` | Subscription |
| GitHub Copilot | `/login github-copilot` | Subscription |
| Google Gemini CLI | `/login google-gemini-cli` | Free |
| Google Antigravity | `/login google-antigravity` | Free |
```bash
pi
/login # Interactive provider selection
/login anthropic # Direct login
/logout # Clear credentials
```
Credentials are stored in `~/.pi/agent/auth.json` and auto-refresh when expired.
### GitHub Copilot
- Press Enter for github.com, or enter your GitHub Enterprise Server domain
- If you get "model not supported", enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
### Google Providers
- **Gemini CLI**: Standard Gemini models via Cloud Code Assist
- **Antigravity**: Sandbox with Gemini 3, Claude, and GPT-OSS models
- Both free with any Google account, subject to rate limits
- For paid Cloud Code Assist: set `GOOGLE_CLOUD_PROJECT` env var
### OpenAI Codex
- Requires ChatGPT Plus or Pro subscription
- Personal use only; for production, use the OpenAI Platform API
## API Keys
Set via environment variable:
```bash
export ANTHROPIC_API_KEY=sk-ant-...
pi
```
| Provider | Environment Variable |
|----------|---------------------|
| Anthropic | `ANTHROPIC_API_KEY` |
| OpenAI | `OPENAI_API_KEY` |
| Google Gemini | `GEMINI_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| Groq | `GROQ_API_KEY` |
| Cerebras | `CEREBRAS_API_KEY` |
| xAI | `XAI_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
| ZAI | `ZAI_API_KEY` |
| OpenCode Zen | `OPENCODE_API_KEY` |
| MiniMax | `MINIMAX_API_KEY` |
| MiniMax (China) | `MINIMAX_CN_API_KEY` |
## Auth File
@ -14,49 +86,32 @@ Store credentials in `~/.pi/agent/auth.json`:
}
```
Auth file keys take priority over environment variables.
The file is created with `0600` permissions (user read/write only). Auth file credentials take priority over environment variables.
## Environment Variables
OAuth credentials are also stored here after `/login` and managed automatically.
| Provider | Auth Key | Environment Variable |
|----------|----------|---------------------|
| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
| OpenAI | `openai` | `OPENAI_API_KEY` |
| Azure OpenAI | `azure-openai` | `AZURE_OPENAI_API_KEY` |
| Google | `google` | `GEMINI_API_KEY` |
| Mistral | `mistral` | `MISTRAL_API_KEY` |
| Groq | `groq` | `GROQ_API_KEY` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` |
| xAI | `xai` | `XAI_API_KEY` |
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` |
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` |
| ZAI | `zai` | `ZAI_API_KEY` |
| OpenCode Zen | `opencode` | `OPENCODE_API_KEY` |
| MiniMax | `minimax` | `MINIMAX_API_KEY` |
| MiniMax (China) | `minimax-cn` | `MINIMAX_CN_API_KEY` |
## Cloud Providers
### Azure OpenAI
Requires additional configuration:
```bash
export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_BASE_URL=https://your-resource.openai.azure.com
# or
# or use resource name instead of base URL
export AZURE_OPENAI_RESOURCE_NAME=your-resource
# Optional
export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4-deployment,gpt-4o=my-gpt4o
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o
```
### Amazon Bedrock
```bash
# Option 1: AWS Profile
export AWS_PROFILE=your-profile-name
export AWS_PROFILE=your-profile
# Option 2: IAM Access Keys
# Option 2: IAM Keys
export AWS_ACCESS_KEY_ID=AKIA...
export AWS_SECRET_ACCESS_KEY=...
@ -64,56 +119,43 @@ export AWS_SECRET_ACCESS_KEY=...
export AWS_BEARER_TOKEN_BEDROCK=...
# Optional region (defaults to us-east-1)
export AWS_REGION=us-east-1
export AWS_REGION=us-west-2
```
Usage:
Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`).
```bash
pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
```
See [Supported models in Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html).
### Google Vertex AI
## OAuth Providers
Use `/login` in interactive mode to authenticate with subscription-based or free-tier providers:
| Provider | Models | Cost |
|----------|--------|------|
| Anthropic (Claude Pro/Max) | Claude models via subscription | Subscription |
| GitHub Copilot | GPT-4o, Claude, Gemini via Copilot | Subscription |
| Google Gemini CLI | Gemini 2.0/2.5 models | Free |
| Google Antigravity | Gemini 3, Claude, GPT-OSS | Free |
| OpenAI Codex (ChatGPT Plus/Pro) | Codex models via ChatGPT | Subscription |
Uses Application Default Credentials:
```bash
pi
/login # Select provider, authorize in browser
gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1
```
Use `/logout` to clear credentials.
Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file.
### GitHub Copilot
## Resolution Order
- Press Enter for github.com, or enter your GitHub Enterprise Server domain
- If you get "model not supported" error, enable it in VS Code: Copilot Chat → model selector → select model → "Enable"
When resolving credentials for a provider:
### Google Providers
- **Gemini CLI**: Production Cloud Code Assist endpoint with standard Gemini models
- **Antigravity**: Sandbox endpoint with Gemini 3, Claude (sonnet/opus thinking), and GPT-OSS
- Both are free with any Google account, subject to rate limits
- Paid Cloud Code Assist subscriptions: set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` env var
### OpenAI Codex
- Requires ChatGPT Plus/Pro subscription
- Personal use only; for production, use the OpenAI Platform API
1. CLI `--api-key` flag (runtime override)
2. API key from `auth.json`
3. OAuth token from `auth.json` (auto-refreshed)
4. Environment variable
5. Custom provider keys from `models.json`
## Troubleshooting
**Port 1455 in use:** Close the conflicting process or paste the auth code/URL when prompted.
**Port 1455 in use:** OAuth callback server can't start. Close the conflicting process or paste the auth URL manually when prompted.
**Token expired / refresh failed:** Run `/login` again to refresh credentials.
**Token expired / refresh failed:** Run `/login` again to re-authenticate.
**Usage limits (429):** Wait for the reset window; pi shows the approximate retry time.
**Rate limits (429):** Wait for the reset window. Pi shows the approximate retry time.
**"model not supported" (GitHub Copilot):** Enable the model in VS Code first.