[DOCS] Errors reference omits the "Your organization has disabled API key authentication" message and v2.1.169 guidance about which credential source to check

Status Fixed / completed

Maintainer reply ✓ Yes — bcherny

Activity 4 comments · opened Jun 9, 2026 · closed Aug 17, 2026

💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/errors

Section/Topic

The "Find your error" table under Authentication and the parallel section in the Login and authentication part of the install troubleshooting guide. The user-facing message is described in the v2.1.169 changelog ("Improved the error message shown when your organization has disabled API key authentication, with guidance based on where the active API key comes from") but the documentation index, error reference, and install troubleshooting guide all omit the message and the key-source guidance entirely.

Current Documentation

docs/code.claude.com/docs/en/errors.md (Find your error table, Authentication rows, lines 33–39):

| Not logged in · Please run /login | [Authentication](#not-logged-in) | | Invalid API key | [Authentication](#invalid-api-key) | | This organization has been disabled | [Authentication](#this-organization-has-been-disabled) | | Your organization has disabled Claude subscription access | [Authentication](#your-organization-has-disabled-claude-subscription-access) | | Routines are disabled by your organization's policy | [Authentication](#routines-are-disabled-by-your-organization%E2%80%99s-policy) | | OAuth token revoked / OAuth token has expired | [Authentication](#oauth-token-revoked-or-expired) |

The page has an Authentication section for the inverse case ("Your organization has disabled Claude subscription access", lines 291–305) where the org blocks subscription logins, but it has no section, and the table has no row, for the case where the org has disabled API-key authentication while still allowing Claude.ai subscription or OAuth.

docs/code.claude.com/docs/en/troubleshoot-install.md (Login and authentication, lines 705–768) likewise has entries for "Reset your login" (709), "OAuth error: Invalid code" (719), "403 Forbidden after login" (729), "This organization has been disabled with an active subscription" (737), "OAuth login fails in WSL2, SSH, or containers" (752), and "Not logged in or token expired" (773). There is no entry covering the org-disabled-API-key-authentication case.

The "Authentication precedence" section in docs/code.claude.com/docs/en/authentication.md (lines 129–140) lists every credential source (CLAUDE_CODE_USE_BEDROCK/VERTEX/FOUNDRY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper, CLAUDE_CODE_OAUTH_TOKEN, subscription OAuth) but does not call out that a Console organization can refuse API-key authentication and surface a different error depending on which source is active.

What's Wrong or Missing?

A. Error reference index omits the message

The "Find your error" table in errors.md has rows for This organization has been disabled and Your organization has disabled Claude subscription access, but no row for the API-key-auth-disabled case. A user hitting the v2.1.169-improved message has no way to find its explanation by matching against the index.

B. No "What to do" guidance that branches on the active key source

The changelog explicitly says the v2.1.169 message "with guidance based on where the active API key comes from". None of the current docs capture that branching. A user reading the error has to guess whether to unset ANTHROPIC_API_KEY, clear apiKeyHelper, drop ANTHROPIC_AUTH_TOKEN, or revoke CLAUDE_CODE_OAUTH_TOKEN. The Authentication precedence list exists, but it is not cross-linked from the new error.

C. Install troubleshooting guide mirrors the gap

troubleshoot-install.md already has a near-twin entry "This organization has been disabled with an active subscription" (line 737) that explains the stale-ANTHROPIC_API_KEY case. The inverse — an org that disables API-key auth — has no parallel entry, so the user has to stumble onto authentication.md or errors.md to recover.

Suggested Improvement

Add a new "Find your error" table row in errors.md:

| Your organization has disabled API key authentication | [Authentication](#your-organization-has-disabled-api-key-authentication) |

Add a new Authentication section in errors.md directly after "Your organization has disabled Claude subscription access" (after line 305) that covers the v2.1.169 message and gives branched "What to do" steps. Suggested body:

### Your organization has disabled API key authentication Your Console organization does not allow Claude Code to authenticate with an Anthropic API key. Running with a key from a disabled or restricted organization returns this error. ``text theme={null} Your organization has disabled API key authentication for Claude Code · Switch to a Claude.ai subscription, or ask your admin to enable API key access ` The hint Claude Code prints is tailored to which credential is currently active, per the [authentication precedence](https://code.claude.com/docs/en/authentication#authentication-precedence) list: **What to do:** * ANTHROPIC_API_KEY is set: unset ANTHROPIC_API_KEY in the current shell and remove the export line from your shell profile (~/.zshrc, ~/.bashrc, or ~/.profile; on Windows, the PowerShell $PROFILE and your User environment variables), then run /status to confirm the active credential. * ANTHROPIC_AUTH_TOKEN is set: unset ANTHROPIC_AUTH_TOKEN and rerun, or rotate the token through your [LLM gateway or proxy](https://code.claude.com/docs/en/llm-gateway). * apiKeyHelper script is set: run the script directly to confirm it prints a key from an organization that permits API-key auth, or update it per the [apiKeyHelper setting](https://code.claude.com/docs/en/settings). * CLAUDE_CODE_OAUTH_TOKEN is set: regenerate the token with claude setup-token and export CLAUDE_CODE_OAUTH_TOKEN=... with a token whose Console organization allows API-key access, or run /login to switch to subscription auth. * Cloud-provider credentials are set (CLAUDE_CODE_USE_BEDROCK/VERTEX/FOUNDRY): API-key auth does not apply; check the [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock), [Google Vertex AI](https://code.claude.com/docs/en/google-vertex-ai), or [Microsoft Foundry](https://code.claude.com/docs/en/microsoft-foundry) page for org-side guidance. * If none of the above apply, your saved /login credentials belong to a restricted org. Run /logout` and sign in with a different account, or contact your admin to enable API-key access for the organization.

Add a parallel "This organization has disabled API key authentication" subsection to troubleshoot-install.md directly after "This organization has been disabled with an active subscription" (line 751) that links into the new errors.md section and shows the same unset commands.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/errors | Find your error table (lines 33–39) and Authentication section (lines 291–305) — index row and dedicated section both missing for the new message |
| https://code.claude.com/docs/en/troubleshoot-install | Login and authentication section (lines 705–768) — twin of "This organization has been disabled with an active subscription" is missing |
| https://code.claude.com/docs/en/authentication | Authentication precedence (lines 129–140) — not cross-linked from the new error |

Total scope: 3 pages affected.

Version: v2.1.169 (June 2026) — message improved per the Improved the error message shown when your organization has disabled API key authentication changelog entry. The error itself is older; v2.1.169 only added the source-specific guidance that this issue asks the docs to reflect.

View original on GitHub ↗

3 Comments

coygeek · 3 months ago

Still relevant as of 2026-07-01. The errors reference at https://code.claude.com/docs/en/errors has been updated: the "Find your error" table now contains a row for Your organization has disabled API key authentication, and a new Authentication section enumerates the four v2.1.169 message variants with branched "What to do" guidance keyed on the active credential source and a link to https://code.claude.com/docs/en/authentication.

However, the install troubleshooting guide at https://code.claude.com/docs/en/troubleshoot-install still has no parallel entry for the inverse case. Its "Login and authentication" section covers "This organization has been disabled with an active subscription" (the stale-ANTHROPIC_API_KEY case) but has no matching subsection for the API-key-disabled case, so users hitting this error during install still have to find their way to the errors reference to recover.

hakonhagland · 2 months ago

Adding two more missing error strings in the same area, plus a case where the documented remediation is actively wrong.

The errors.md table has a row for OAuth token revoked / OAuth token has expired pointing at OAuth token revoked or expired, whose code block reads:

OAuth token revoked · Please run /login
OAuth token has expired · Please run /login
API Error: 401 ... authentication_error

That covers the stored /login credential. A token supplied through CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token) produces different text that appears nowhere in the docs. Observed on 2.1.220, in a container with no other credential present:

Failed to authenticate. API Error: 401 OAuth access token has been revoked.
Failed to authenticate. API Error: 401 OAuth access token is invalid.

The first is a token revoked at claude.ai/settings/claude-code; the second is a malformed or non-existent token. Neither matches the documented strings closely enough to find by searching the error index, which is the stated purpose of that table.

The remediation problem. The existing section's "What to do" is run /login, and for an env-var token that advice cannot work. Per the authentication precedence list, CLAUDE_CODE_OAUTH_TOKEN (5) outranks the stored /login credential (6) — so signing in writes a credential the env var still shadows, and the error persists. In the CI and headless environments this token exists for, there is no /login to run at all. The correct recovery is to mint a replacement with claude setup-token and update the environment variable (and note that minting does not invalidate the old token, so the old one should also be revoked at claude.ai/settings/claude-code).

Suggested: two rows in the "Find your error" table for the OAuth access token has been revoked / is invalid strings, and either a short subsection or a branch inside the existing one that keys the remediation to the credential source, the way this issue already argues for the API-key-disabled message.

For what it's worth, the Not logged in · Please run /login row is exactly right — that is verbatim what a container with no credential prints. The gap is specifically the env-var token variants.

bcherny collaborator · 2 months ago

The errors reference now has an entry for this message, including which credential source to check: https://code.claude.com/docs/en/errors#your-organization-has-disabled-api-key-authentication

🤖 Generated with Claude Code

Showing cached comments. Read the full discussion on GitHub ↗