#3196: docs: clarify auth-profiles.json format for Claude Max setup-tokens
docs
Cluster:
Auth Improvements and Fixes
Fixes #3098
## Summary
- Add explicit `auth-profiles.json` format examples for setup-tokens in `docs/providers/anthropic.md`
- Add comprehensive credential type examples in `docs/concepts/oauth.md`
- Clarify that setup-tokens require `type: "token"` (not `"oauth"`)
## The Problem
When configuring `auth-profiles.json` manually for Claude Max/Pro setup-tokens, using `type: "oauth"` with
`accessToken` fails silently. The correct format is:
```json
{
"type": "token",
"provider": "anthropic",
"token": "sk-ant-oat01-..."
}
```
## Test plan
- [x] Verify JSON examples are syntactically correct
- [x] Cross-reference with source types in `src/agents/auth-profiles/types.ts`
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR updates the documentation to prevent misconfigurations when manually editing per-agent `auth-profiles.json`, especially for Anthropic Claude subscription “setup-token” auth. It adds explicit JSON examples for the three credential shapes used by the auth profile store (`api_key`, `token`, and `oauth`) in `docs/concepts/oauth.md`, and adds a dedicated “Manual auth-profiles.json setup” section to `docs/providers/anthropic.md` that clarifies setup-tokens must use `type: "token"` (not `"oauth"` / `accessToken`).
These changes align with the credential union in `src/agents/auth-profiles/types.ts` and should reduce silent failures from using the wrong credential type while keeping auth storage documentation centralized under the OAuth/token-sink concept.
<h3>Confidence Score: 4/5</h3>
- This PR is safe to merge; changes are documentation-only with low operational risk.
- Edits are confined to docs and largely match the existing auth profile types, with only a small potential for minor schema drift in the OAuth example fields.
- docs/concepts/oauth.md (OAuth example field names)
<!-- greptile_other_comments_section -->
<sub>(3/5) Reply to the agent's comments like "Can you suggest a fix for this @greptileai?" or ask follow-up questions!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#10492: fix(auth): store Anthropic setup-token as type:oauth for auto-refresh
by sparck75 · 2026-02-06
83.3%
#2123: fix(auth): sync from Claude CLI keychain before OAuth refresh
by jorge123255 · 2026-01-26
82.3%
#13484: feat(auth): restore Claude Code CLI OAuth credential sync
by joshpocock · 2026-02-10
79.8%
#6400: fix: set correct mode for Anthropic OAuth auth (#2697)
by coupclawbot · 2026-02-01
78.9%
#3909: fix(auth): refresh all OAuth profiles per provider
by Daviey · 2026-01-29
77.8%
#10961: feat: Support routingHint and improve URL routing for Anthropic (Cl...
by catveloper · 2026-02-07
77.7%
#9163: Fix: Save Anthropic setup token to config file
by vishaltandale00 · 2026-02-04
77.6%
#7523: fix(auth): re-sync external CLI credentials on token revocation
by codeslayer44 · 2026-02-02
77.5%
#14368: fix: skip auth profile cooldown on format errors to prevent provide...
by koatora20 · 2026-02-12
77.0%
#16362: Update session-pruning.md - updated agents.defaults config std
by elliottb · 2026-02-14
77.0%