claude-code - 💡(How to fix) Fix [DOCS] Vertex AI workload identity federation docs missing `ANTHROPIC_WORKSPACE_ID` workspace-scoping guidance [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/google-vertex-ai

Section/Topic

"3. Configure GCP credentials", "Advanced credential configuration", and "4. Configure Claude Code"

Current Documentation

The Google Vertex AI guide currently says:

Claude Code v2.1.121 or later supports X.509 certificate-based Workload Identity Federation through the same Application Default Credentials chain. Set GOOGLE_APPLICATION_CREDENTIALS to the path of your credential configuration file.

It also says:

Claude Code uses ANTHROPIC_VERTEX_PROJECT_ID as the project ID for Vertex AI requests. The GCLOUD_PROJECT and GOOGLE_CLOUD_PROJECT environment variables and the credential file referenced by GOOGLE_APPLICATION_CREDENTIALS take precedence over it.

Later, the setup example includes:

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

The environment variables reference currently documents ANTHROPIC_VERTEX_PROJECT_ID, but does not document ANTHROPIC_WORKSPACE_ID.

What's Wrong or Missing?

The v2.1.141 release entry adds ANTHROPIC_WORKSPACE_ID for workload identity federation so the minted token can be scoped to a specific workspace when one federation rule covers multiple workspaces, but the Claude Code docs do not explain this anywhere.

That leaves a gap in the current Vertex AI guidance:

A. Missing variable reference

There is no ANTHROPIC_WORKSPACE_ID entry in the environment variable reference, so users cannot discover that this variable exists or what header/scope it affects.

B. Missing WIF setup guidance

The workload identity federation section explains ADC setup and project selection, but not when a workspace-scoping variable is required.

C. Missing relationship to existing Vertex config

The docs explain ANTHROPIC_VERTEX_PROJECT_ID, but not how ANTHROPIC_WORKSPACE_ID fits alongside it for multi-workspace federation configurations.

Suggested Improvement

Add ANTHROPIC_WORKSPACE_ID to the environment variables reference and extend the Vertex AI workload identity federation docs with a short explanation and example.

Suggested addition:

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID
export ANTHROPIC_WORKSPACE_ID=wrkspc_...
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/wif-config.json

The accompanying text should explain that ANTHROPIC_WORKSPACE_ID is needed when the federation rule can mint tokens for more than one Anthropic workspace, and that setting it scopes the minted token to the intended workspace.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version: This gap appears after the v2.1.141 release entry that introduced ANTHROPIC_WORKSPACE_ID for workload identity federation workspace scoping.