Skip to main content

Claude Code

Tasks

Route Claude Code traffic through AIControls to get full audit coverage and policy enforcement. Two modes are supported. Which one you use depends on how your workspace is configured — if only one mode is enabled it is applied automatically, and if both are enabled you choose your authentication method when you create an access token or during onboarding.

Prerequisites​

  • Claude Code installed — npm install -g @anthropic-ai/claude-code
  • Your workspace proxy URL — find it in Settings → Integrations
  • A personal access token — create one in Settings → Access Tokens

Proxy vs Passthrough​

AIControls holds your organization's Anthropic API key. You authenticate with your personal access token — no Anthropic credentials on your machine.

Step 1 — Remove existing Anthropic credentials​

If you've previously authenticated with an Anthropic API key, clear it so Claude Code doesn't prefer saved credentials over the proxy:

claude auth logout 2>/dev/null || true

Step 2 — Configure ~/.claude/settings.json​

Open or create ~/.claude/settings.json and add:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://YOUR_ORG.aicontrols.dev",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_ACCESS_TOKEN"
  }
}

Replace YOUR_ORG with your workspace subdomain and YOUR_ACCESS_TOKEN with your personal access token.

note

Use ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY. Claude Code treats these differently — ANTHROPIC_AUTH_TOKEN signals a virtual token and prevents Claude Code from validating the format against Anthropic's key schema.

tip

Your virtual token is scoped to your identity. It cannot be used to extract the organization's API key — you authenticate to AIControls, which then forwards requests to Anthropic using the org credential.

Claude for Work​

If your team uses Claude for Work (the claude.ai web or desktop app on Enterprise or Team plans), an administrator can configure AIControls as the AI Gateway for your whole organization. When set up, all claude.ai traffic from your workspace routes through AIControls automatically — no per-developer configuration required.

Admin configuration​

  1. In your claude.ai Enterprise admin settings, open Workspace settings → AI Gateway.
  2. Enable the third-party AI gateway option.
  3. Set the gateway URL to your workspace proxy endpoint: https://YOUR_ORG.aicontrols.dev
  4. Save. Traffic from all claude.ai users in your organization immediately routes through AIControls.
note

Claude for Work traffic appears in your Audit Log under Source: Claude for Work. Governance uses the organization token, not personal access tokens — attribution is by claude.ai user identity.

MCP tool governance​

If you use Claude Code with MCP servers, AIControls intercepts every tool call — no additional configuration needed. MCP traffic flows through the same proxy endpoint as LLM requests.

To see which MCP tools are being called and what policies apply, go to Audit Log and filter by Type: Tool call.

Verify the connection​

Start Claude Code and make any request — ask it to read a file or summarize a function. Then check your workspace Audit Log. Within a few seconds you should see the request with your identity and model details.

Troubleshooting​

Requests not appearing in Audit Log​

  • Confirm ANTHROPIC_BASE_URL is set in ~/.claude/settings.json (no trailing slash)
  • Restart Claude Code after editing settings — env vars from settings.json take effect on startup
  • Check that your access token is valid — try regenerating it in Settings → Access Tokens

Authentication errors (proxy mode)​

  • Ensure you're using ANTHROPIC_AUTH_TOKEN, not ANTHROPIC_API_KEY
  • Run claude auth logout to clear any cached Anthropic credentials that may take precedence
  • Confirm your workspace URL matches the one in Settings → Integrations

Authentication errors (passthrough mode)​

  • Check that ANTHROPIC_CUSTOM_HEADERS is set to exactly X-AIControls-Token: YOUR_ACCESS_TOKEN (no extra spaces)
  • Confirm your personal access token hasn't expired — regenerate it in Settings → Access Tokens if needed

Requests denied by policy​

If a request is blocked, Claude Code shows an error. Check Audit Log → Denied for the policy that triggered and the denial reason. Contact your administrator to adjust the policy or get an exemption.

Last updated on