[plan] Expand auth.mdx to cover provider-based and OAuth authentication for all engines #25058

Objective

Expand docs/src/content/docs/reference/auth.mdx to cover provider-based and OAuth authentication for all supported engines (Copilot, Claude, Codex), which is currently undocumented.

Context

Issue #16498 has been open since February 2026. The gap is now more urgent because Copilot CLI 1.0.19 (issue #25014) added BYOK, which overlaps with provider-based auth. auth.mdx currently only covers the API key method; OAuth and cloud-provider auth paths are missing entirely.

CLAUDE_CODE_OAUTH_TOKEN is used in workflow code but not documented. Users have no guidance on which secrets to configure for each engine.

Files to Modify

• docs/src/content/docs/reference/auth.mdx — primary target

Approach

1. Restructure auth.mdx with engine-specific sections:

   • Copilot: GitHub token auth (current), plus BYOK via COPILOT_PROVIDER_* env vars (link to BYOK page created in the companion issue)
   • Claude: ANTHROPIC_API_KEY (API key), CLAUDE_CODE_OAUTH_TOKEN (OAuth — document this explicitly), and any provider-based options
   • Codex: OPENAI_API_KEY and any Azure/provider variants

2. Add a "Which secret do I need?" quick-reference table: engine → required secret(s) → optional alternatives — this is the most common question new users have.

3. Document CLAUDE_CODE_OAUTH_TOKEN: when to use OAuth vs API key, how to obtain the token, and how to store it as a repository secret.

4. Document Codex authentication options including Azure variants if supported.

5. Add a "Troubleshooting auth errors" section with common error messages and fixes.

Acceptance Criteria

• All three engines (Copilot, Claude, Codex) have their own auth section
• CLAUDE_CODE_OAUTH_TOKEN is documented with instructions for obtaining and using it
• Quick-reference table exists mapping engine → required secret(s)
• BYOK / provider-based auth for Copilot is covered (or cross-linked to BYOK page)
• Troubleshooting section covers the most common auth errors
• No references to undocumented env vars remain
  Related to [Daily Report] Documentation Quality Report — April 7, 2026 #25041

Generated by Plan Command for issue #25041 · ● 360.6K · ◷

• expires on Apr 9, 2026, 10:34 AM UTC