From 726e0a4b5b3d067c936103fc634841b5ec22f6d8 Mon Sep 17 00:00:00 2001 From: Mario Zechner Date: Sun, 25 Jan 2026 21:42:20 +0100 Subject: [PATCH] docs(coding-agent): rewrite authentication.md with proper structure - Subscriptions first (OAuth providers) - Clear API keys table - Auth file format - Cloud providers section (Azure, Bedrock, Vertex) - Resolution order - Troubleshooting --- packages/coding-agent/docs/authentication.md | 160 ++++++++++++------- 1 file changed, 101 insertions(+), 59 deletions(-) diff --git a/packages/coding-agent/docs/authentication.md b/packages/coding-agent/docs/authentication.md index aa9a1d07..284de14f 100644 --- a/packages/coding-agent/docs/authentication.md +++ b/packages/coding-agent/docs/authentication.md @@ -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.