llms.txt@13-Enterprise-Admin · git:20260521.1b74b3e · 2026-05-21 · sha256 0198e744aa56f314

llms.txt@13-Enterprise-Admin git:20260521.1b74b3eF

Immutable. This exact content never changes and is served at /api/v1/blob/0198e744aa56f314.

# Enterprise Admin

All documentation for Enterprise Admin.

---
## access-audit-logs.md

# Access audit logs

Audit logs are available for Enterprise organizations only.

Organization Owners and Primary Owners can export data within **[Organization settings \> Data and Privacy](https://claude.ai/admin-settings/data-privacy-controls)** and clicking the "Export logs" button. Upon triggering this export, all audit logs for the organization within the past 180 days will be aggregated. The Owner who requested the export will receive an email containing a download link, which is active for 24 hours. Note that there may be a delay between triggering the export and receiving the email as logs are aggregated.

Please note that title and content of chats and projects are not available to be exported in audit logs (only their unique identifiers will be exported). However, chat inputs/outputs will be exportable by Primary Owners via **[data exports](https://support.claude.com/en/articles/9450526-how-can-i-export-my-claude-data)**.

**Note:** Audit log events are available in the Compliance API. For more information, refer to **[Access the Compliance API](https://support.claude.com/en/articles/13015708-access-the-compliance-api)**.

## Log Structure

Audit logs consist of the following columns:

[TABLE]

## Entities

The entities that can be affected by events. Entity info follows this structure:

[TABLE]

## Recorded Events

[TABLE]

---
## analytics.md

> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Track team usage with analytics

> View Claude Code usage metrics, track adoption, and measure engineering velocity in the analytics dashboard.

Claude Code provides analytics dashboards to help organizations understand developer usage patterns, track contribution metrics, and measure how Claude Code impacts engineering velocity. Access the dashboard for your plan:

| Plan | Dashboard URL | Includes | Read more |
| ----------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| Claude for Teams / Enterprise | [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code) | Usage metrics, contribution metrics with GitHub integration, leaderboard, data export | [Details](#access-analytics-for-teams-and-enterprise) |
| API (Claude Console) | [platform.claude.com/claude-code](https://platform.claude.com/claude-code) | Usage metrics, spend tracking, team insights | [Details](#access-analytics-for-api-customers) |

## Access analytics for Teams and Enterprise

Navigate to [claude.ai/analytics/claude-code](https://claude.ai/analytics/claude-code). Admins and Owners can view the dashboard.

The Teams and Enterprise dashboard includes:

* **Usage metrics**: lines of code accepted, suggestion accept rate, daily active users and sessions
* **Contribution metrics**: PRs and lines of code shipped with Claude Code assistance, with [GitHub integration](#enable-contribution-metrics)
* **Leaderboard**: top contributors ranked by Claude Code usage
* **Data export**: download contribution data as CSV for custom reporting

### Enable contribution metrics

<Note>
Contribution metrics are in public beta and available on Claude for Teams and Claude for Enterprise plans. These metrics only cover users within your claude.ai organization. Usage through the Claude Console API or third-party integrations is not included.
</Note>

Usage and adoption data is available for all Claude for Teams and Claude for Enterprise accounts. Contribution metrics require additional setup to connect your GitHub organization.

You need the Owner role to configure analytics settings. A GitHub admin must install the GitHub app.

<Steps>
<Step title="Install the GitHub app">
A GitHub admin installs the Claude GitHub app on your organization's GitHub account at [github.com/apps/claude](https://github.com/apps/claude).
</Step>

<Step title="Enable Claude Code analytics">
A Claude Owner navigates to [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) and enables the Claude Code analytics feature.
</Step>

<Step title="Enable GitHub analytics">
On the same page, enable the "GitHub analytics" toggle.
</Step>

<Step title="Authenticate with GitHub">
Complete the GitHub authentication flow and select which GitHub organizations to include in the analysis.
</Step>
</Steps>

Data typically appears within 24 hours after enabling, with daily updates. If no data appears, you may see one of these messages:

* **"GitHub app required"**: install the GitHub app to view contribution metrics
* **"Data processing in progress"**: check back in a few days and confirm the GitHub app is installed if data doesn't appear

Contribution metrics support GitHub Cloud and GitHub Enterprise Server.

### Review summary metrics

<Note>
These metrics are deliberately conservative and represent an underestimate of Claude Code's actual impact. Only lines and PRs where there is high confidence in Claude Code's involvement are counted.
</Note>

The dashboard displays these summary metrics at the top:

* **PRs with CC**: total count of merged pull requests that contain at least one line of code written with Claude Code
* **Lines of code with CC**: total lines of code across all merged PRs that were written with Claude Code assistance. Only "effective lines" are counted: lines with more than 3 characters after normalization, excluding empty lines and lines with only brackets or trivial punctuation.
* **PRs with Claude Code (%)**: percentage of all merged PRs that contain Claude Code-assisted code
* **Suggestion accept rate**: percentage of times users accept Claude Code's code editing suggestions, including Edit, Write, and NotebookEdit tool usage
* **Lines of code accepted**: total lines of code written by Claude Code that users have accepted in their sessions. This excludes rejected suggestions and does not track subsequent deletions.

### Explore the charts

The dashboard includes several charts to visualize trends over time.

#### Track adoption

The Adoption chart shows daily usage trends:

* **users**: daily active users
* **sessions**: number of active Claude Code sessions per day

#### Measure PRs per user

This chart displays individual developer activity over time:

* **PRs per user**: total number of PRs merged per day divided by daily active users
* **users**: daily active users

Use this to understand how individual productivity changes as Claude Code adoption increases.

#### View pull requests breakdown

The Pull requests chart shows a daily breakdown of merged PRs:

* **PRs with CC**: pull requests containing Claude Code-assisted code
* **PRs without CC**: pull requests without Claude Code-assisted code

Toggle to **Lines of code** view to see the same breakdown by lines of code rather than PR count.

#### Find top contributors

The Leaderboard shows the top 10 users ranked by contribution volume. Toggle between:

* **Pull requests**: shows PRs with Claude Code vs All PRs for each user
* **Lines of code**: shows lines with Claude Code vs All lines for each user

Click **Export all users** to download complete contribution data for all users as a CSV file. The export includes all users, not just the top 10 displayed.

### PR attribution

When contribution metrics are enabled, Claude Code analyzes merged pull requests to determine which code was written with Claude Code assistance. This is done by matching Claude Code session activity against the code in each PR.

#### Tagging criteria

PRs are tagged as "with Claude Code" if they contain at least one line of code written during a Claude Code session. The system uses conservative matching: only code where there is high confidence in Claude Code's involvement is counted as assisted.

#### Attribution process

When a pull request is merged:

1. Added lines are extracted from the PR diff
2. Claude Code sessions that edited matching files within a time window are identified
3. PR lines are matched against Claude Code output using multiple strategies
4. Metrics are calculated for AI-assisted lines and total lines

Before comparison, lines are normalized: whitespace is trimmed, multiple spaces are collapsed, quotes are standardized, and text is converted to lowercase.

Merged pull requests containing Claude Code-assisted lines are labeled as `claude-code-assisted` in GitHub.

#### Time window

Sessions from 21 days before to 2 days after the PR merge date are considered for attribution matching.

#### Excluded files

Certain files are automatically excluded from analysis because they are auto-generated:

* Lock files: package-lock.json, yarn.lock, Cargo.lock, and similar
* Generated code: Protobuf outputs, build artifacts, minified files
* Build directories: dist/, build/, node\_modules/, target/
* Test fixtures: snapshots, cassettes, mock data
* Lines over 1,000 characters, which are likely minified or generated

#### Attribution notes

Keep these additional details in mind when interpreting attribution data:

* Code substantially rewritten by developers, with more than 20% difference, is not attributed to Claude Code
* Sessions outside the 21-day window are not considered
* The algorithm does not consider the PR source or destination branch when performing attribution

### Get the most from analytics

Use contribution metrics to demonstrate ROI, identify adoption patterns, and find team members who can help others get started.

#### Monitor adoption

Track the Adoption chart and user counts to identify:

* Active users who can share best practices
* Overall adoption trends across your organization
* Dips in usage that may indicate friction or issues

#### Measure ROI

Contribution metrics help answer "Is this tool worth the investment?" with data from your own codebase:

* Track changes in PRs per user over time as adoption increases
* Compare PRs and lines of code shipped with vs. without Claude Code
* Use alongside [DORA metrics](https://dora.dev/), sprint velocity, or other engineering KPIs to understand changes from adopting Claude Code

#### Identify power users

The Leaderboard helps you find team members with high Claude Code adoption who can:

* Share prompting techniques and workflows with the team
* Provide feedback on what's working well
* Help onboard new users

#### Access data programmatically

To query this data through GitHub, search for PRs labeled with `claude-code-assisted`.

## Access analytics for API customers

API customers using the Claude Console can access analytics at [platform.claude.com/claude-code](https://platform.claude.com/claude-code). You need the UsageView permission to access the dashboard, which is granted to Developer, Billing, Admin, Owner, and Primary Owner roles.

<Note>
Contribution metrics with GitHub integration are not currently available for API customers. The Console dashboard shows usage and spend metrics only.
</Note>

The Console dashboard displays:

* **Lines of code accepted**: total lines of code written by Claude Code that users have accepted in their sessions. This excludes rejected suggestions and does not track subsequent deletions.
* **Suggestion accept rate**: percentage of times users accept code editing tool usage, including Edit, Write, and NotebookEdit tools.
* **Activity**: daily active users and sessions shown on a chart.
* **Spend**: daily API costs in dollars alongside user count.

### View team insights

The team insights table shows per-user metrics:

* **Members**: all users who have authenticated to Claude Code. API key users display by key identifier, OAuth users display by email address.
* **Spend this month**: per-user total API costs for the current month.
* **Lines this month**: per-user total of accepted code lines for the current month.

<Note>
Spend figures in the Console dashboard are estimates for analytics purposes. For actual costs, refer to your billing page.
</Note>

## Related resources

* [Monitoring with OpenTelemetry](monitoring-claude-code-docs-72c46f3dc8.md): export real-time metrics and events to your observability stack
* [Manage costs effectively](../02-Claude-Code-CLI/costs.md): set spend limits and optimize token usage
* [Identity and access management](/en/iam): configure roles and permissions

---
## authentication-claude-code-docs-2c6ada8385.md

# Authentication

Claude Code supports multiple authentication methods depending on your setup. Individual users can log in with a Claude.ai account, while teams can use Claude for Teams or Enterprise, the Claude Console, or a cloud provider like Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

[](#log-in-to-claude-code)

After [installing Claude Code](/docs/en/setup#install-claude-code), run `claude` in your terminal. On first launch, Claude Code opens a browser window for you to log in. If the browser doesn’t open automatically, press `c` to copy the login URL to your clipboard, then paste it into your browser. If your browser shows a login code instead of redirecting back after you sign in, paste it into the terminal at the `Paste code here if prompted` prompt. You can authenticate with any of these account types:

- **Claude Pro or Max subscription**: log in with your Claude.ai account. Subscribe at [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code&utm_medium=docs&utm_content=authentication_pro_max).
- **Claude for Teams or Enterprise**: log in with the Claude.ai account your team admin invited you to.
- **Claude Console**: log in with your Console credentials. Your admin must have [invited you](#claude-console-authentication) first.
- **Cloud providers**: if your organization uses [Amazon Bedrock](/docs/en/amazon-bedrock), [Google Vertex AI](/docs/en/google-vertex-ai), or [Microsoft Foundry](/docs/en/microsoft-foundry), set the required environment variables before running `claude`. No browser login is needed.

To log out and re-authenticate, type `/logout` at the Claude Code prompt. If you’re having trouble logging in, see [authentication troubleshooting](/docs/en/troubleshooting#authentication-issues).

[](#set-up-team-authentication)

Set up team authentication

For teams and organizations, you can configure Claude Code access in one of these ways:

- [Claude for Teams or Enterprise](#claude-for-teams-or-enterprise), recommended for most teams
- [Claude Console](#claude-console-authentication)
- [Amazon Bedrock](/docs/en/amazon-bedrock)
- [Google Vertex AI](/docs/en/google-vertex-ai)
- [Microsoft Foundry](/docs/en/microsoft-foundry)

[](#claude-for-teams-or-enterprise)

Claude for Teams or Enterprise

[Claude for Teams](https://claude.com/pricing?utm_source=claude_code&utm_medium=docs&utm_content=authentication_teams#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=authentication_enterprise) provide the best experience for organizations using Claude Code. Team members get access to both Claude Code and Claude on the web with centralized billing and team management.

- **Claude for Teams**: self-service plan with collaboration features, admin tools, and billing management. Best for smaller teams.
- **Claude for Enterprise**: adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings for organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.

Subscribe to [Claude for Teams](https://claude.com/pricing?utm_source=claude_code&utm_medium=docs&utm_content=authentication_teams_step#team-&-enterprise) or contact sales for [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=authentication_enterprise_step).

Invite team members

Invite team members from the admin dashboard.

Install and log in

Team members install Claude Code and log in with their Claude.ai accounts.

[](#claude-console-authentication)

Claude Console authentication

For organizations that prefer API-based billing, you can set up access through the Claude Console.

Create or use a Console account

Use your existing Claude Console account or create a new one.

Add users

You can add users through either method:

- Bulk invite users from within the Console: Settings -\> Members -\> Invite
- [Set up SSO](../21-Account-Support/setting-up-single-sign-on-sso.md)

Assign roles

When inviting users, assign one of:

- **Claude Code** role: users can only create Claude Code API keys
- **Developer** role: users can create any kind of API key

Users complete setup

Each invited user needs to:

- Accept the Console invite
- [Check system requirements](/docs/en/setup#system-requirements)
- [Install Claude Code](/docs/en/setup#install-claude-code)
- Log in with Console account credentials

[](#cloud-provider-authentication)

Cloud provider authentication

For teams using Amazon Bedrock, Google Vertex AI, or Microsoft Foundry:

Follow provider setup

Follow the [Bedrock docs](/docs/en/amazon-bedrock), [Vertex docs](/docs/en/google-vertex-ai), or [Microsoft Foundry docs](/docs/en/microsoft-foundry).

Distribute configuration

Distribute the environment variables and instructions for generating cloud credentials to your users. Read more about how to [manage configuration here](/docs/en/settings).

Install Claude Code

Users can [install Claude Code](/docs/en/setup#install-claude-code).

[](#credential-management)

Credential management

Claude Code securely manages your authentication credentials:

- **Storage location**: on macOS, credentials are stored in the encrypted macOS Keychain. On Linux and Windows, credentials are stored in `~/.claude/.credentials.json`, or under `$CLAUDE_CONFIG_DIR` if that variable is set. On Linux, the file is written with mode `0600`; on Windows, it inherits the access controls of your user profile directory.
- **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.
- **Custom credential scripts**: the [`apiKeyHelper`](/docs/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.
- **Refresh intervals**: by default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.
- **Slow helper notice**: if `apiKeyHelper` takes longer than 10 seconds to return a key, Claude Code displays a warning notice in the prompt bar showing the elapsed time. If you see this notice regularly, check whether your credential script can be optimized.

`apiKeyHelper`, `ANTHROPIC_API_KEY`, and `ANTHROPIC_AUTH_TOKEN` apply to terminal CLI sessions only. Claude Desktop and remote sessions use OAuth exclusively and do not call `apiKeyHelper` or read API key environment variables.

[](#authentication-precedence)

Authentication precedence

When multiple credentials are present, Claude Code chooses one in this order:

1. Cloud provider credentials, when `CLAUDE_CODE_USE_BEDROCK`, `CLAUDE_CODE_USE_VERTEX`, or `CLAUDE_CODE_USE_FOUNDRY` is set. See [third-party integrations](/docs/en/third-party-integrations) for setup.
2. `ANTHROPIC_AUTH_TOKEN` environment variable. Sent as the `Authorization: Bearer` header. Use this when routing through an [LLM gateway or proxy](/docs/en/llm-gateway) that authenticates with bearer tokens rather than Anthropic API keys.
3. `ANTHROPIC_API_KEY` environment variable. Sent as the `X-Api-Key` header. Use this for direct Anthropic API access with a key from the [Claude Console](../04-API-Reference/Other/platform-claude-com.md). In interactive mode, you are prompted once to approve or decline the key, and your choice is remembered. To change it later, use the “Use custom API key” toggle in `/config`. In non-interactive mode (`-p`), the key is always used when present.
4. [`apiKeyHelper`](/docs/en/settings#available-settings) script output. Use this for dynamic or rotating credentials, such as short-lived tokens fetched from a vault.
5. `CLAUDE_CODE_OAUTH_TOKEN` environment variable. A long-lived OAuth token generated by [`claude setup-token`](#generate-a-long-lived-token). Use this for CI pipelines and scripts where browser login isn’t available.
6. Subscription OAuth credentials from `/login`. This is the default for Claude Pro, Max, Team, and Enterprise users.

If you have an active Claude subscription but also have `ANTHROPIC_API_KEY` set in your environment, the API key takes precedence once approved. This can cause authentication failures if the key belongs to a disabled or expired organization. Run `unset ANTHROPIC_API_KEY` to fall back to your subscription, and check `/status` to confirm which method is active. [Claude Code on the Web](/docs/en/claude-code-on-the-web) always uses your subscription credentials. `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` in the sandbox environment do not override them.

[](#generate-a-long-lived-token)

Generate a long-lived token

For CI pipelines, scripts, or other environments where interactive browser login isn’t available, generate a one-year OAuth token with `claude setup-token`:

```python
claude setup-token
```

The command walks you through OAuth authorization and prints a token to the terminal. It does not save the token anywhere; copy it and set it as the `CLAUDE_CODE_OAUTH_TOKEN` environment variable wherever you want to authenticate:

```python
export CLAUDE_CODE_OAUTH_TOKEN=your-token
```

This token authenticates with your Claude subscription and requires a Pro, Max, Team, or Enterprise plan. It is scoped to inference only and cannot establish [Remote Control](/docs/en/remote-control) sessions. [Bare mode](/docs/en/headless#start-faster-with-bare-mode) does not read `CLAUDE_CODE_OAUTH_TOKEN`. If your script passes `--bare`, authenticate with `ANTHROPIC_API_KEY` or an `apiKeyHelper` instead.

---
## business-associate-agreements-baa-for-commercial-customers.md

3. Business Associate Agreements (BAA) for Commercial Customers

# Business Associate Agreements (BAA) for Commercial Customers

*This article is about our commercial products such as Claude for Work and the Anthropic API. For our consumer products such as Claude Free, Pro, Max and when accounts from those plans use Claude Code, see* ***[here](https://privacy.claude.com/en/collections/10663362-consumers)****.*

After review of HIPAA-related compliance items and your specific use case, Anthropic may provide a Business Associate Agreement (BAA) covering our HIPAA-ready services, such as use of our first-party API or Enterprise plans.

For our first-party API, our BAA is only available for customers who qualify for certain HIPAA-ready services such as those subject to **[zero data retention agreements](https://privacy.claude.com/en/articles/8956058-i-have-a-zero-data-retention-agreement-with-anthropic-what-products-does-it-apply-to)**.

For clarity, the BAA does not cover Workbench and Console, Claude Free, Pro, Max, or Team plans, and other beta or chat products, features, or integrations. As part of the BAA, customers of Anthropic’s HIPAA-ready services are subject to certain configuration requirements and limitations on what features/integrations are available.

Below is a breakdown of what’s covered under the BAA, by feature and product surface.

## What’s covered under Anthropic’s BAA

[TABLE]

## Product BAA coverage by surface

[TABLE]

To learn more about Anthropic’s HIPAA-ready services or begin the BAA process, please submit an inquiry with the details of your deployment to our **[Sales team via this form](https://claude.com/contact-sales)**.

Please see our **[Trust Portal](https://trust.anthropic.com/resources?s=rgirr4qe8u7ek8c2igx3&name=claude-for-enterprise-hipaa-ready-offering-implementation-guide)** for more information about our compliance commitments.

---
## claude-enterprise-analytics-api-reference-guide.md

4. Claude Enterprise Analytics API reference guide

# Claude Enterprise Analytics API reference guide

## Overview

The Claude Enterprise Analytics API gives your organization programmatic access to engagement data for Claude and Claude Code usage within your Enterprise organization. Whether you're building internal dashboards for user activity or tracking adoption of projects, this API provides the aggregated metrics you need.

## Data aggregation

All data is aggregated **per organization, per day**. Each endpoint returns a snapshot for a single date that you specify. **Data for day (N-1) is run at 10:00:00 UTC time on day N**, and is available for querying three days after aggregation, to ensure accuracy of data.

If data is not available within the timeline above, this usually indicates a data pipeline failure that our team will need to investigate internally. We are usually aware of such problems, but please raise this to your CSM if you want a gut check, or suspect something else.

## Enabling access

In order to mint new analytics API keys, you must be a Primary Owner within your Enterprise organization. You can do so by navigating to **[claude.ai/analytics/api-keys](http://claude.ai/analytics/api-keys)**.

Some more details that might be helpful:

- You can *enable/disable* access to the public API anytime. If you disable access by toggling the switch off, all requests will be denied.

- You’ll need a key with the `read:analytics` scope in order to access the API. You can create multiple keys for your organization, but rate limits apply at the *organization* level, not the *key* level. See the “Rate limiting” section below.

- As always, *we strongly recommend handling API keys securely*: *never* share these keys publicly - they are secret, and should be shared securely.

## Base URL

All requests are sent to:

https://api.anthropic.com/v1/organizations/analytics/

## Authentication

Every request requires an API key passed in the `x-api-key` header. Your API key must have the `read:analytics` scope. You can create and manage API keys from the claude.ai admin settings under the API Keys section.

**Example request headers:**

x-api-key: $YOUR_API_KEY

## Pagination

Several endpoints return paginated results. Pagination uses a cursor-based approach, where the response includes a `next_page` token you pass back in your next request to retrieve the following page of results.

Two optional parameters control pagination:

**limit** (integer): Number of records per page. Defaults to 20 for the /users endpoint and 100 for all other endpoints. The maximum is 1000.

**page** (string): The opaque cursor token from the previous response's `next_page` field. Omit this on your first request.

When there are no more results, `next_page` will be `null` in the response.

## Error responses

All endpoints return standard HTTP error codes:

[TABLE]

## Rate limiting

We do have default rate limits in place. If that isn’t sufficient for your use case, we’d love to understand why. If necessary, we can adjust the rate limits for your organization—please reach out to your CSM.

## Endpoints

### 1. List user activity

`GET /v1/organizations/analytics/users`

Returns per-user engagement metrics for a single day. Each item in the response represents one user and includes their activity counts across Claude (chat) and Claude Code.

**Query parameters**

[TABLE]

**Response fields (per user)**

[TABLE]

**Example request**

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/users?date=2025-01-01&limit=3"
--header "x-api-key: $YOUR_API_KEY"

### 2. Activity summary

`GET /v1/organizations/analytics/summaries`

Returns a high-level summary of engagement and seat utilization **per-day** for your organization for a given date range. The response is a list of days with aggregated counts within the date range. Note that the maximum difference between `ending_date` and `starting_date` must be **31 days**, and there is a three-day delay in data availability. This is useful for tracking daily active users, weekly and monthly trends, and seat allocation at a glance.

**We define “active”** if any one of the following is true:

- The user sent at least one chat message on Claude (chat).

- The user had at least one Claude Code (local or remote) session associated with the C4E org, with tool use/git activity

**Query parameters**

[TABLE]

**Response fields**

[TABLE]

**Note:** The rolling windows for weekly and monthly counts look backward from the specified date (inclusive). If data is incomplete for some days within the window (for example, if the date is less than 30 days in the past), the monthly count may undercount activity.

**Example request**

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/summaries?starting_date=2025-01-01"
--header "x-api-key: $YOUR_API_KEY"

### 3. Chat project usage

`GET /v1/organizations/analytics/apps/chat/projects`

Returns usage data broken down by chat project for a given date. Projects are specific to Claude (chat), so this endpoint focuses on that surface. Each item shows the project name, how many unique users interacted with it, and the total number of conversations held in that project.

**Query parameters**

[TABLE]

**Response fields (per project)**

[TABLE]

**Example request**

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/apps/chat/projects?date=2025-01-01&limit=50"
--header "x-api-key: $YOUR_API_KEY"

### 4. Skill usage

`GET /v1/organizations/analytics/skills`

Returns skill usage data across both Claude (chat) and Claude Code within your organization for a given date. Each item represents a skill and shows how many unique users used it.

**Query parameters**

[TABLE]

**Response fields (per skill)**

[TABLE]

**Example request**

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/skills?date=2025-01-01"
--header "x-api-key: $YOUR_API_KEY"

### 5. Connector usage

`GET /v1/organizations/analytics/connectors`

Returns MCP/connector usage data across both Claude (chat) and Claude Code within your organization for a given date. Each item represents a connector and shows how many unique users used it. Connector names are normalized from various sources — for example, "Atlassian MCP server," "mcp-atlassian," and "atlassian_MCP" would all appear as "atlassian."

**Query parameters**

[TABLE]

**Response fields (per connector)**

[TABLE]

**Example request**

curl -X GET "https://api.anthropic.com/v1/organizations/analytics/connectors?date=2025-01-01"
--header "x-api-key: $YOUR_API_KEY"

---
## claude-for-chrome-admin-controls.md

# Claude in Chrome admin controls

Claude in Chrome admin controls are available in beta for Team and Enterprise plans.

This article explains how Team and Enterprise Owners can manage Claude in Chrome for their organization.

Claude in Chrome is a browser extension that allows Claude to read, click, and navigate websites on behalf of your users. As an Owner, you control whether the extension is available for users to install and which sites they can access.

**Important:** Before enabling Claude in Chrome for your organization, review **[Using Claude in Chrome safely](../15-Claude-AI-Features/using-claude-for-chrome-safely.md)** to understand the risks of browser-based AI, including prompt injection attacks.

## Accessing Claude in Chrome settings

To manage Claude in Chrome settings for your organization:

1. Sign in to Claude with your Owner account.

2. Navigate to **[Organization settings \> Claude in Chrome](http://claude.ai/admin-settings/browser-extension)**.

## Enabling or disabling the extension

Use the toggle to enable or disable Claude in Chrome for your entire organization.

- **Team plans:** The extension is enabled by default. Disable it if you prefer users not to have access.

- **Enterprise plans:** The extension is disabled by default. Enable it when you're ready for users to access the feature.

**Note:** When you enable the extension for an Enterprise organization, users are not automatically notified. You may want to communicate availability through your internal channels.

## Configuring site access

Use allowlists and blocklists to control which websites Claude can access when users are working with the extension.

**Allowlist:** Specify which sites Claude is permitted to access by adding them to the allowlist. We recommend starting with a restrictive allowlist, especially during initial rollout.

**Blocklist:** Specify sites Claude should never access, regardless of other settings, by adding them to the blocklist. This adds an extra layer of protection beyond **[Claude's default blocked categories](../15-Claude-AI-Features/using-claude-for-chrome-safely.md#h_34f8d5ca87)**.

**Recommendation:** Start with a more restrictive allowlist for the security of your organization's data, then expand access over time as you become comfortable with the extension's behavior.

## Managing user access on Claude Desktop

Users with both Claude in Chrome and Claude Desktop installed will now have the option to start a task on the desktop app and let it handle work in the browser without switching windows.

If you want to disable this for members of your organization, you can toggle the extension off entirely, or edit your Enterprise configuration.

**Disable the Chrome extension in organization settings:**

1. Click your initials in the lower left corner, then select “Organization settings.”

2. Navigate to “Connectors.”

3. Find **Claude in Chrome** in the list and click “Configure.”

4. Toggle the connector off.

Alternatively, disable `isLocalDevMcpEnabled` in **[your Enterprise configuration](enterprise-configuration.md)**.

## Deployment options

Once enabled, users can access Claude in Chrome in two ways:

- **Self-service:** Users install the extension themselves from the **[Chrome Web Store](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)**.

- **Managed deployment:** Use your existing Chrome management tools (Google Workspace admin console or MDM) to deploy the extension to specific users or groups.

Most Enterprise organizations already have Chrome extension management in place. You can use these existing controls to limit which employees can install the extension during a pilot phase.

## Running a pilot

To test Claude in Chrome with a subset of users before broader rollout:

1. Enable the extension at the organization level.

2. Configure a restrictive allowlist limiting Claude to specific, trusted sites.

3. Use your IT controls to limit which employees can install the extension.

4. Share **[Using Claude in Chrome safely](../15-Claude-AI-Features/using-claude-for-chrome-safely.md)** with pilot users.

5. Gather feedback and expand access over time.

## Educating your users

We recommend sharing these resources with users before they start using Claude in Chrome:

- **[Getting started with Claude in Chrome](../15-Claude-AI-Features/getting-started-with-claude-for-chrome.md)**: Installation and core capabilities

- **[Using Claude in Chrome safely](../15-Claude-AI-Features/using-claude-for-chrome-safely.md)**: Risks and best practices

- **[Claude in Chrome permissions guide](../15-Claude-AI-Features/claude-for-chrome-permissions-guide.md)**: How users control what Claude can access

---
## claude-in-chrome-admin-controls.md

# Claude in Chrome admin controls

Claude in Chrome admin controls are available in beta for Team and Enterprise plans.

This article explains how Team and Enterprise Owners can manage Claude in Chrome for their organization.

## Accessing Claude in Chrome settings

To manage Claude in Chrome settings for your organization:

1. Sign in to Claude with your Owner account.

2. Navigate to **[Organization settings \> Claude in Chrome](http://claude.ai/admin-settings/browser-extension)**.

## Enabling or disabling the extension

Use the toggle to enable or disable Claude in Chrome for your entire organization.

- **Team plans:** The extension is enabled by default. Disable it if you prefer users not to have access.

- **Enterprise plans:** The extension is disabled by default. Enable it when you're ready for users to access the feature.

**Note:** When you enable the extension for an Enterprise organization, users are not automatically notified. You may want to communicate availability through your internal channels.

## Configuring site access

Use allowlists and blocklists to control which websites Claude can access when users are working with the extension.

**Allowlist:** Specify which sites Claude is permitted to access by adding them to the allowlist. We recommend starting with a restrictive allowlist, especially during initial rollout.

**Recommendation:** Start with a more restrictive allowlist for the security of your organization's data, then expand access over time as you become comfortable with the extension's behavior.

## Managing user access on Claude Desktop

Users with both Claude in Chrome and Claude Desktop installed will now have the option to start a task on the desktop app and let it handle work in the browser without switching windows.

If you want to disable this for members of your organization, you can toggle the extension off entirely, or edit your Enterprise configuration.

**Disable the Chrome extension in organization settings:**

1. Click your initials in the lower left corner, then select “Organization settings.”

2. Navigate to “Connectors.”

3. Find **Claude in Chrome** in the list and click “Configure.”

4. Toggle the connector off.

Alternatively, disable `isLocalDevMcpEnabled` in **[your Enterprise configuration](enterprise-configuration.md)**.

## Deployment options

Once enabled, users can access Claude in Chrome in two ways:

- **Self-service:** Users install the extension themselves from the **[Chrome Web Store](https://chromewebstore.google.com/detail/claude/fcoeoabgfenejglbffodgkkbkcdhcgfn)**.

- **Managed deployment:** Use your existing Chrome management tools (Google Workspace admin console or MDM) to deploy the extension to specific users or groups.

Most Enterprise organizations already have Chrome extension management in place. You can use these existing controls to limit which employees can install the extension during a pilot phase.

## Running a pilot

To test Claude in Chrome with a subset of users before broader rollout:

1. Enable the extension at the organization level.

2. Configure a restrictive allowlist limiting Claude to specific, trusted sites.

3. Use your IT controls to limit which employees can install the extension.

4. Share **[Using Claude in Chrome safely](../15-Claude-AI-Features/using-claude-for-chrome-safely.md)** with pilot users.

5. Gather feedback and expand access over time.

## Educating your users

We recommend sharing these resources with users before they start using Claude in Chrome:

- **[Getting started with Claude in Chrome](../15-Claude-AI-Features/getting-started-with-claude-for-chrome.md)**: Installation and core capabilities

- **[Using Claude in Chrome safely](../15-Claude-AI-Features/using-claude-for-chrome-safely.md)**: Risks and best practices

- **[Claude in Chrome permissions guide](../15-Claude-AI-Features/claude-for-chrome-permissions-guide.md)**: How users control what Claude can access

---
## configure-server-managed-settings-claude-code-docs-d6a169b0bf.md

# Configure server-managed settings

Centrally configure Claude Code for your organization through server-delivered settings, without requiring device management infrastructure.

Server-managed settings allow administrators to centrally configure Claude Code through a web-based interface on Claude.ai. Claude Code clients automatically receive these settings when users authenticate with their organization credentials. This approach is designed for organizations that do not have device management infrastructure in place, or need to manage settings for users on unmanaged devices.

Server-managed settings are available for [Claude for Teams](https://claude.com/pricing?utm_source=claude_code&utm_medium=docs&utm_content=server_settings_teams#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code&utm_medium=docs&utm_content=server_settings_enterprise) customers.

[](#requirements)

Requirements

To use server-managed settings, you need:

- Claude for Teams or Claude for Enterprise plan
- Claude Code version 2.1.38 or later for Claude for Teams, or version 2.1.30 or later for Claude for Enterprise
- Network access to `api.anthropic.com`

[](#choose-between-server-managed-and-endpoint-managed-settings)

Choose between server-managed and endpoint-managed settings

Claude Code supports two approaches for centralized configuration. Server-managed settings deliver configuration from Anthropic’s servers. [Endpoint-managed settings](/docs/en/settings#settings-files) are deployed directly to devices through native OS policies (macOS managed preferences, Windows registry) or managed settings files.

| Approach | Best for | Security model |
|:---|:---|:---|
| **Server-managed settings** | Organizations without MDM, or users on unmanaged devices | Settings delivered from Anthropic’s servers at authentication time |
| **[Endpoint-managed settings](/docs/en/settings#settings-files)** | Organizations with MDM or endpoint management | Settings deployed to devices via MDM configuration profiles, registry policies, or managed settings files |

If your devices are enrolled in an MDM or endpoint management solution, endpoint-managed settings provide stronger security guarantees because the settings file can be protected from user modification at the OS level.

[](#configure-server-managed-settings)

Configure server-managed settings

Open the admin console

In [Claude.ai](https://claude.ai), navigate to **Admin Settings \> Claude Code \> Managed settings**.

Define your settings

Add your configuration as JSON. All [settings available in `settings.json`](/docs/en/settings#available-settings) are supported, including [hooks](/docs/en/hooks), [environment variables](/docs/en/env-vars), and [managed-only settings](/docs/en/permissions#managed-only-settings) like `allowManagedPermissionRulesOnly`.This example enforces a permission deny list, prevents users from bypassing permissions, and restricts permission rules to those defined in managed settings:

```python
{
"permissions": {
"deny": [
"Bash(curl *)",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
],
"disableBypassPermissionsMode": "disable"
},
"allowManagedPermissionRulesOnly": true
}
```

Hooks use the same format as in `settings.json`.This example runs an audit script after every file edit across the organization:

```python
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
]
}
]
}
}
```

To configure the [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) classifier so it knows which repos, buckets, and domains your organization trusts:

```python
{
"autoMode": {
"environment": [
"Source control: github.example.com/acme-corp and all repos under it",
"Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",
"Trusted internal domains: *.corp.example.com"
]
}
}
```

Because hooks execute shell commands, users see a [security approval dialog](#security-approval-dialogs) before they’re applied. See [Configure auto mode](/docs/en/auto-mode-config) for how the `autoMode` entries affect what the classifier blocks and important warnings about the `allow` and `soft_deny` fields.

Save and deploy

Save your changes. Claude Code clients receive the updated settings on their next startup or hourly polling cycle.

[](#verify-settings-delivery)

Verify settings delivery

To confirm that settings are being applied, ask a user to restart Claude Code. If the configuration includes settings that trigger the [security approval dialog](#security-approval-dialogs), the user sees a prompt describing the managed settings on startup. You can also verify that managed permission rules are active by having a user run `/permissions` to view their effective permission rules.

[](#access-control)

Access control

The following roles can manage server-managed settings:

- **Primary Owner**
- **Owner**

Restrict access to trusted personnel, as settings changes apply to all users in the organization.

[](#managed-only-settings)

Managed-only settings

Most [settings keys](/docs/en/settings#available-settings) work in any scope. A handful of keys are only read from managed settings and have no effect when placed in user or project settings files. See [managed-only settings](/docs/en/permissions#managed-only-settings) for the full list. Any setting not on that list can still be placed in managed settings and takes the highest precedence.

[](#current-limitations)

Current limitations

Server-managed settings have the following limitations:

- Settings apply uniformly to all users in the organization. Per-group configurations are not yet supported.
- [MCP server configurations](/docs/en/mcp#managed-mcp-configuration) cannot be distributed through server-managed settings.

[](#settings-delivery)

Settings delivery

[](#settings-precedence)

Settings precedence

Server-managed settings and [endpoint-managed settings](/docs/en/settings#settings-files) both occupy the highest tier in the Claude Code [settings hierarchy](/docs/en/settings#settings-precedence). No other settings level can override them, including command line arguments. Within the managed tier, the first source that delivers a non-empty configuration wins. Server-managed settings are checked first, then endpoint-managed settings. Sources do not merge: if server-managed settings deliver any keys at all, endpoint-managed settings are ignored entirely. If server-managed settings deliver nothing, endpoint-managed settings apply. If you clear your server-managed configuration in the admin console with the intent of falling back to an endpoint-managed plist or registry policy, be aware that [cached settings](#fetch-and-caching-behavior) persist on client machines until the next successful fetch. Run `/status` to see which managed source is active.

[](#fetch-and-caching-behavior)

Fetch and caching behavior

Claude Code fetches settings from Anthropic’s servers at startup and polls for updates hourly during active sessions. **First launch without cached settings:**

- Claude Code fetches settings asynchronously
- If the fetch fails, Claude Code continues without managed settings
- There is a brief window before settings load where restrictions are not yet enforced

**Subsequent launches with cached settings:**

- Cached settings apply immediately at startup
- Claude Code fetches fresh settings in the background
- Cached settings persist through network failures

Claude Code applies settings updates automatically without a restart, except for advanced settings like OpenTelemetry configuration, which require a full restart to take effect.

[](#enforce-fail-closed-startup)

Enforce fail-closed startup

By default, if the remote settings fetch fails at startup, the CLI continues without managed settings. For environments where this brief unenforced window is unacceptable, set `forceRemoteSettingsRefresh: true` in your managed settings. When this setting is active, the CLI blocks at startup until remote settings are freshly fetched. If the fetch fails, the CLI exits rather than proceeding without the policy. This setting self-perpetuates: once delivered from the server, it is also cached locally so that subsequent startups enforce the same behavior even before the first successful fetch of a new session. To enable this, add the key to your managed settings configuration:

```python
{
"forceRemoteSettingsRefresh": true
}
```

Before enabling this setting, ensure your network policies allow connectivity to `api.anthropic.com`. If that endpoint is unreachable, the CLI exits at startup and users cannot start Claude Code.

[](#security-approval-dialogs)

Security approval dialogs

Certain settings that could pose security risks require explicit user approval before being applied:

- **Shell command settings**: settings that execute shell commands
- **Custom environment variables**: variables not in the known safe allowlist
- **Hook configurations**: any hook definition

When these settings are present, users see a security dialog explaining what is being configured. Users must approve to proceed. If a user rejects the settings, Claude Code exits.

In non-interactive mode with the `-p` flag, Claude Code skips security dialogs and applies settings without user approval.

[](#platform-availability)

Platform availability

Server-managed settings require a direct connection to `api.anthropic.com` and are not available when using third-party model providers:

- Amazon Bedrock
- Google Vertex AI
- Microsoft Foundry
- Custom API endpoints via `ANTHROPIC_BASE_URL` or [LLM gateways](/docs/en/llm-gateway)

[](#audit-logging)

Audit logging

Audit log events for settings changes are available through the compliance API or audit log export. Contact your Anthropic account team for access. Audit events include the type of action performed, the account and device that performed the action, and references to the previous and new values.

[](#security-considerations)

Security considerations

Server-managed settings provide centralized policy enforcement, but they operate as a client-side control. On unmanaged devices, users with admin or sudo access can modify the Claude Code binary, filesystem, or network configuration.

| Scenario | Behavior |
|:---|:---|
| User edits the cached settings file | Tampered file applies at startup, but correct settings restore on the next server fetch |
| User deletes the cached settings file | First-launch behavior occurs: settings fetch asynchronously with a brief unenforced window |
| API is unavailable | Cached settings apply if available, otherwise managed settings are not enforced until the next successful fetch. With `forceRemoteSettingsRefresh: true`, the CLI exits instead of continuing |
| User authenticates with a different organization | Settings are not delivered for accounts outside the managed organization |
| User sets a non-default `ANTHROPIC_BASE_URL` | Server-managed settings are bypassed when using third-party API providers |

To detect runtime configuration changes, use [`ConfigChange` hooks](/docs/en/hooks#configchange) to log modifications or block unauthorized changes before they take effect. For stronger enforcement guarantees, use [endpoint-managed settings](/docs/en/settings#settings-files) on devices enrolled in an MDM solution.

[](#see-also)

See also

Related pages for managing Claude Code configuration:

- [Settings](/docs/en/settings): complete configuration reference including all available settings
- [Endpoint-managed settings](/docs/en/settings#settings-files): managed settings deployed to devices by IT
- [Authentication](/docs/en/authentication): set up user access to Claude Code
- [Security](/docs/en/security): security safeguards and best practices

---
## console-log-warning.local.md

You're adding a console.log statement. Please consider:
- Is this for debugging or should it be proper logging?
- Will this ship to production?
- Should this use a logging library instead?

---
## custom-data-retention-controls-for-claude-enterprise.md

4. Configure custom data retention controls for Enterprise plans

# Configure custom data retention controls for Enterprise plans

This feature is available to Enterprise plan customers. To set custom retention periods for your organization, you must have either a Primary Owner or Owner role.

*This article is about our commercial products such as Claude for Work and the Anthropic API. For our consumer products such as Claude Free, Pro, Max and when accounts from those plans use Claude Code, see **[here](https://privacy.claude.com/en/collections/10663362-consumers)**.*

Custom data retention controls allow organizations to manage how long Claude stores conversation and project data. This article explains how to set up and manage data retention periods for your organization.

## How data retention works

Data retention is based on the last observed activity:

- **For chats:** Retention period starts from the time of the last message in the conversation.

- **For projects:** Retention period starts from the time the project was last updated (this includes chat creation or project knowledge base modifications).

- Note that your custom data retention periods set for projects will supersede your custom retention periods for any chats.

The minimum retention period is 30 days, and each month is counted as 30 days. For example, a three-month retention period equals 90 days.

## What gets deleted

When data reaches the end of its retention period:

- **For chats:** All chats (including chats within projects) and any artifacts within those chats will be deleted.

- **For projects:** All projects will be deleted, including any chats and artifacts within those projects.

## Important considerations

- Deletion occurs at midnight UTC on the scheduled day.

- By default, data is retained indefinitely unless a custom retention period is set.

- When you modify retention settings, any data that falls outside the new retention period will be deleted immediately upon saving.

- Data past its retention period will be permanently deleted and cannot be recovered.

## Setting up data retention

## To set custom retention periods:

1. Log in to your Owner Enterprise plan account.

2. Navigate to **[Organization settings \> Data and Privacy](https://claude.ai/admin-settings/data-privacy-controls)**.

3. Set your desired retention period (minimum 30 days).

4. Save your changes.

## Example retention calculation

If a conversation’s last message is at 3PM UTC on March 1 with a 30-day retention period, the deletion will occur at midnight UTC on March 31.

## Monitoring retention-related activities

All retention-related actions and changes are automatically tracked in **[audit logs](https://support.claude.com/en/articles/9970975-how-to-access-audit-logs)**. You can access these logs to monitor changes to retention settings and data deletion events.

---
## deploying-enterprise-grade-mcp-servers-with-desktop-extensions.md

4. Deploying enterprise-grade MCP servers with desktop extensions

# Deploying enterprise-grade MCP servers with desktop extensions

Updated today

Desktop extensions are installable packages that run Model Context Protocol (MCP) servers locally on your machine. They provide Claude Desktop with secure access to your local resources, internal systems, and personal tools without the complexity of remote infrastructure.

With desktop extensions, you can deploy enterprise-grade MCP implementations with fine-grained admin controls. This article explains why desktop extensions are valuable for organizations and how to use them effectively.

## Why use desktop extensions?

### Seamless authentication

Desktop extensions operate within your corporate network boundaries, using the user’s existing authenticated context without requiring additional firewall rules or VPN configurations. They leverage existing SSO and browser sessions automatically with no token management required – credentials stay securely on user devices.

### Access internal resources

Desktop extensions connect to internal wikis, JIRA, Confluence, and other systems behind your firewall. They can query private databases and APIs without VPN configuration, connect to on-premises systems like SAP, Oracle, and custom applications, and access internal resources without exposing them on public infrastructure.

### Read and manipulate local resources

Desktop extensions provide access to local resources that remote connectors cannot reach. This includes direct filesystem access for code editing and Git operations, integration with locally installed tools like Docker, IDEs, and databases, control over desktop applications via local APIs, and hardware integration for specialized workflows.

### Instant deployment with minimal infrastructure overhead

One-click installation through Claude Desktop comes with no dependencies to manage. The built-in [Node.js](http://node.js) runtime is included, there’s no cloud infrastructure to provision, and updates are distributed directly through the extension marketplace.

### Enterprise-grade controls

Organization owners can upload custom extensions to their organization and control which desktop extensions their users have access to through the desktop extension allowlist. To learn more about managing desktop extensions in your organization, see Enabling and using the desktop extension allowlist.

## Enterprise use cases

**Multiple enterprises are building desktop extensions to serve a variety of use cases:**

- As secure proxies to internal MCP servers, giving them complete control over access, authentication, and audit logs while maintaining their zero-trust architecture.

- To give Claude access to internal documentation and knowledge bases.

- To connect to development tools and databases securely, and maintain complete control over authentication, authorization, and audit logging.

Desktop extensions eliminate the traditional tradeoff between security and usability—providing Claude with powerful capabilities while maintaining your enterprise security posture.

---
## does-anthropic-act-as-a-data-processor-or-controller.md

4. Does Anthropic Act as a Data Processor or Controller?

# Does Anthropic Act as a Data Processor or Controller?

*This article is about our commercial products such as Claude for Work and the Anthropic API. For our consumer products such as Claude Free, Pro, Max and when accounts from those plans use Claude Code, see* *[here](https://privacy.claude.com/en/collections/10663362-consumers).*

When a commercial customer creates a Claude for Work account (Team or Enterprise plan), under our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) the customer is the "Controller" of the data submitted by its Users. This means:

- The customer has control over who can be a member of their team and provides us with instructions for how submitted data can be used.

- The customer may access and export data (such as conversation history) submitted by its Users.

- Anthropic acts as a "Processor" of the data on behalf of the customer. Anthropic only processes the data as instructed by the customer in order to provide the Claude service.

- Anthropic does not use the data you share when using our commercial products to train our models, unless you choose to participate in our [Development Partner Program](https://support.claude.com/en/articles/11174108-about-the-development-partner-program).

In summary, for Claude for Work, the customer organization maintains control over their Users' data, and Anthropic only processes that data to provide the service on the customer's behalf, according to our agreement. You should consult with your organization's administrators regarding Claude usage policies.

## Resources

For more details on our data practices, please see the:

- [Anthropic Privacy Center](https://privacy.claude.com/en/collections/10663361-commercial-customers)

- [Anthropic Trust Center](http://trust.anthropic.com)

- [Anthropic Privacy Policy](https://www.anthropic.com/legal/privacy)

---
## enforce-network-level-access-control-with-tenant-restrictions.md

4. Enforce network-level access control with Tenant Restrictions

# Enforce network-level access control with Tenant Restrictions

Tenant Restrictions are available for members of Enterprise plans and Console organizations.

Tenant Restrictions enable IT administrators on Enterprise plans to enforce network-level access control for Claude. This feature ensures that users on corporate networks can only access approved organizational accounts, preventing unauthorized use of personal accounts.

## How it works

When enabled, your network proxy injects an HTTP header into requests to Claude. Anthropic validates this header and blocks access from any organization not in the allowed list.

**Supported authentication methods:**

- Web access ([claude.ai](http://claude.ai))

- Desktop / App Access

- API key authentication

- OAuth token authentication

## Header format

anthropic-allowed-org-ids: <org-uuid-1>,<org-uuid-2>,...

- Comma-delimited list of organization UUIDs

- No spaces between values

**Example:**

anthropic-allowed-org-ids: 550e8400-e29b-41d4-a716-446655440000,6ba7b810-
9dad-11d1-80b4-00c04fd430c8

## Configuration steps

### 1. Find your organization UUID

Members of Enterprise plans can find this in two different places:

1. Navigate to **[Settings \> Account](https://claude.ai/settings/account)** and find **Organization ID**.

2. Navigate to **[Organization settings \> Organization](https://claude.ai/admin-settings/organization)** and scroll down to the bottom of the page to locate **Organization ID**.

Members of Console organizations can find this in **[Settings \> Organization](https://platform.claude.com/settings/organization)**.

### 2. Configure your network proxy

Configure your proxy to inject the header for Claude traffic:

Rule: Claude Tenant Restriction
Application: claude.ai, api.anthropic.com, claude.com, anthropic.com
Action: Inject Header
Header Name: anthropic-allowed-org-ids
Header Value:
TLS Inspection: Required

### 3. Test your configuration

From restricted network, test with your org's API key:

curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $CLAUDE_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-6","max_tokens":1024,"messages":
[{"role":"user","content":"Hello"}]}'

## Error response

When access is blocked, users receive the following error:

{
"type": "error",
"error": {
"type": "permission_error",
"message": "Access restricted by network policy. Contact IT Administrator.",
"error_code": "tenant_restriction_violation"
}
}

## Supported proxy platforms

- Zscaler ZIA (Cloud App Control policies)

- Palo Alto Prisma Access (SaaS App Management)

- Cato Networks (Tenant Restriction policy)

- Netskope (Header Insertion rules)

- Generic HTTPS proxies with header injection capability

## Use cases

[TABLE]

## Security benefits

- **Data Loss Prevention:** Block personal account usage from corporate networks.

- **Compliance:** Enforce data residency and access policies.

- **Shadow IT Control:** Prevent unauthorized Claude usage.

- **Audit Trail:** Complete visibility into access attempts.

## Backward compatibility

- No impact to networks without tenant restrictions configured.

- Standard authentication continues for unmanaged networks.

- Existing API key authentication remains unchanged.

---
## enterprise-architecture-diagram.md

# Claude Code Enterprise Architecture — System Interconnections

**Date**: 2026-03-13
**Visual Reference**: How all enterprise systems connect together

---

## High-Level Enterprise Platform Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│ ORGANIZATION MANAGEMENT LAYER │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────────┐ │
│ │ Organization │ │ Seat Tiers │ │ Member Accounts │ │
│ │ UUID: org-123 │───▶│ - Free │───▶│ user@example.com │ │
│ │ Name: "Acme" │ │ - Pro │ │ Role: admin │ │
│ │ Type: Enterprise│ │ - Max │ │ Credits: 10000 │ │
│ └──────────────────┘ │ - Enterprise │ └────────────────────┘ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
┌────────────────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ BILLING & CREDITS │ │ ACCESS CONTROL │ │ ENTERPRISE INFRA │
│ │ │ │ │ │
│ Credit Balance │ │ Permission │ │ Provider Routing │
│ Overage Tracking │ │ Checks (4-tier) │ │ - AWS Bedrock │
│ Usage Limits │ │ - Org level │ │ - Google Vertex │
│ Admin Requests │ │ - Seat level │ │ - MS Foundry │
│ - limit_increase │ │ - Member level │ │ │
│ │ │ - Service level │ │ Unix Socket Mode │
│ Referral Campaigns │ │ │ │ Policy Enforcement │
│ - Guest passes │ │ Role System │ │ Plugin Management │
└────────────────────────┘ │ - user │ └─────────────────────┘
│ │ - admin │ │
│ └──────────────────┘ │
│ │ │
└───────────────────────┼────────────────────────┘
│
▼
┌────────────────────────────────┐
│ RUNTIME ENFORCEMENT │
│ │
│ - Fast mode enable/disable │
│ - Feature gating │
│ - Usage telemetry │
│ - Audit logging │
└────────────────────────────────┘
```

---

## Credit & Overage System Flow

```
┌─────────────────────────────────────────────────────────────────────────┐
│ CREDIT ALLOCATION HIERARCHY │
└─────────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐
│ Organization Credit Pool │
│ - Total allocated: 100,000 │
│ - org_service_zero_credit_limit │
└──────────────────┬───────────────────────────────┘
│
┌─────────────┴─────────────┬─────────────────┐
│ │ │
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌──────────────┐
│ Seat Tier 1 │ │ Seat Tier 2 │ │ Seat Tier N │
│ (Pro) │ │ (Enterprise) │ │ (Free) │
│ Limit: 5,000 │ │ Limit: 25k │ │ Limit: 500 │
│ ──────────── │ │ ──────────── │ │ ────────────│
│ seat_tier_ │ │ seat_tier_ │ │ seat_tier_ │
│ zero_credit_ │ │ zero_credit_ │ │ zero_credit_│
│ limit │ │ limit │ │ limit │
└────────┬───────┘ └────────┬───────┘ └──────┬───────┘
│ │ │
┌────┴────┬─────┐ ┌────┴────┐ ┌────┴────┐
│ │ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│Member│ │Member│ │Member│ │Member│ │Member│ │Member│ │Member│
│ user1│ │ user2│ │ user3│ │ user4│ │ user5│ │ user6│ │ user7│
│──────│ │──────│ │──────│ │──────│ │──────│ │──────│ │──────│
│member│ │member│ │member│ │member│ │member│ │member│ │member│
│_zero │ │_zero │ │_zero │ │_zero │ │_zero │ │_zero │ │_zero │
│_cred │ │_cred │ │_cred │ │_cred │ │_cred │ │_cred │ │_cred │
│it_ │ │it_ │ │it_ │ │it_ │ │it_ │ │it_ │ │it_ │
│limit │ │limit │ │limit │ │limit │ │limit │ │limit │ │limit │
└──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘

┌─────────────────────────────────────────────────────────────────────────┐
│ OVERAGE HANDLING │
└─────────────────────────────────────────────────────────────────────────┘

Member usage flow:

1. Normal usage (within limit)
│
├─ Credits deducted from member allocation
│
▼
2. Limit reached → Switch to overage mode
│
├─ isUsingOverage = true
├─ Charges against overage pool
├─ User notified: "Using extra usage"
│
▼
3. Overage pool exhausted
│
├─ overageDisabledReason = "out_of_credits"
├─ Fast mode disabled
├─ User sees: "You're out of extra usage · resets <time>"
│
▼
4. Admin intervention
│
├─ User requests: POST /admin_requests {type: "limit_increase"}
├─ Admin approves via dashboard
├─ Credits replenished
│
▼
5. Back to normal usage
```

---

## Permission Check Flow (4-Tier System)

```
User attempts to use Fast Mode
│
├─ Check 1: Organization Level
│ │
│ ├─ Is feature org_level_disabled? ──────────────────────┐
│ ├─ Is feature org_level_disabled_until <timestamp>? ────┤
│ ├─ Is org_service_level_disabled? ──────────────────────┤
│ └─ Is org_service_zero_credit_limit? ───────────────────┤
│ │
├─ Check 2: Seat Tier Level │
│ │ │
│ ├─ Does seat tier include Fast Mode? │
│ ├─ Is seat_tier_level_disabled? ────────────────────────┤
│ └─ Is seat_tier_zero_credit_limit? ─────────────────────┤
│ │
├─ Check 3: Member Level │
│ │ │
│ ├─ Is user member_level_disabled? ───────────────────────┤
│ └─ Is member_zero_credit_limit? ────────────────────────┤
│ │
├─ Check 4: Service Level (runtime) │
│ │ │
│ ├─ Network connectivity OK? │
│ ├─ Not using enterprise provider (Bedrock/Vertex)? │
│ └─ Not in Agent SDK mode? │
│ │
▼ ▼
✅ ALLOW ❌ DENY
Fast Mode enabled Show reason:
- "extra usage disabled"
- "not available on <provider>"
- "network issues"
```

---

## Admin Request Workflow

```
┌──────────────────────────────────────────────────────────────────────┐
│ LIMIT INCREASE REQUEST FLOW │
└──────────────────────────────────────────────────────────────────────┘

User (member_zero_credit_limit)
│
├─ 1. Check Eligibility
│ GET /api/oauth/organizations/{orgId}/admin_requests/eligibility
│ ?request_type=limit_increase
│
▼
┌──────────────┐
│ Eligible? │
└───┬──────────┘
│ YES
▼
┌─────────────────────┐
│ 2. Submit Request │
│ POST /admin_requests│
│ { │
│ request_type: │
│ "limit_increase", │
│ details: {...} │
│ } │
└──────┬──────────────┘
│
│ Request ID: req-abc123
│
▼
┌──────────────────────────┐
│ 3. Admin Dashboard │
│ https://claude.ai/ │
│ admin-settings/usage │
│ │
│ Pending Requests: │
│ ┌────────────────────┐ │
│ │ user@example.com │ │
│ │ Requested: +5000 │ │
│ │ Current: 1000 │ │
│ │ [Approve] [Deny] │ │
│ └────────────────────┘ │
└──────┬───────────────────┘
│
│ Admin approves
│
▼
┌──────────────────────┐
│ 4. Limit Updated │
│ member_credit_limit │
│ 1000 → 6000 │
└──────┬───────────────┘
│
▼
User notified via UI:
"Your limit increase was approved"
```

---

## Enterprise Provider Routing

```
┌──────────────────────────────────────────────────────────────────────┐
│ ENTERPRISE PROVIDER SELECTION │
└──────────────────────────────────────────────────────────────────────┘

Organization configuration:
└─ enterpriseProvider: "bedrock" | "vertex" | "foundry" | null

┌───────────────┐
│ User Request │
│ (Sonnet 4.6) │
└───────┬───────┘
│
├─ Check org enterpriseProvider
│
▼
┌─────────────────────────────────────────────────────┐
│ Provider Routing Decision │
├─────────────────────────────────────────────────────┤
│ │
│ IF CLAUDE_CODE_USE_BEDROCK=1: │
│ └─ Route to AWS Bedrock │
│ - Model: "anthropic.claude-sonnet-4-6-v1" │
│ - Auth: IAM or AWS_BEARER_TOKEN_BEDROCK │
│ - Fast mode: DISABLED │
│ │
│ ELSE IF CLAUDE_CODE_USE_VERTEX=1: │
│ └─ Route to Google Vertex AI │
│ - Model: "claude-sonnet-4-6@20260311" │
│ - Auth: Application Default Credentials │
│ - Fast mode: DISABLED │
│ │
│ ELSE IF CLAUDE_CODE_USE_FOUNDRY=1: │
│ └─ Route to Microsoft Foundry │
│ - Model: "claude-sonnet-4-6" │
│ - Auth: Azure AD or ANTHROPIC_FOUNDRY_API_KEY │
│ - Fast mode: DISABLED │
│ │
│ ELSE: │
│ └─ Route to Anthropic (first-party) │
│ - Model: "claude-sonnet-4-6" │
│ - Auth: ANTHROPIC_API_KEY or OAuth │
│ - Fast mode: ENABLED (if credits allow) │
│ │
└─────────────────────────────────────────────────────┘
```

---

## Unix Socket Proxy Architecture (Zero-Trust Mode)

```
┌──────────────────────────────────────────────────────────────────────┐
│ UNIX SOCKET ENTERPRISE PROXY │
│ (Added in 2.1.74) │
└──────────────────────────────────────────────────────────────────────┘

Enterprise Environment:

┌───────────────────────────────────────────────────────┐
│ Corporate Network (kubernetes/docker) │
│ │
│ ┌───────────────────────────────────────────────┐ │
│ │ Pod: claude-code-worker │ │
│ │ │ │
│ │ Environment: │ │
│ │ ❌ ANTHROPIC_API_KEY=<not set> │ │
│ │ ❌ AWS_ACCESS_KEY_ID=<stripped> │ │
│ │ ✅ ANTHROPIC_UNIX_SOCKET=/run/claude.sock │ │
│ │ ✅ CLAUDE_CODE_OAUTH_TOKEN=<token> │ │
│ │ │ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ Claude Code Process │ │ │
│ │ │ (restricted subprocess) │ │ │
│ │ │ │ │ │
│ │ │ ✓ All creds stripped from env │ │ │
│ │ │ ✓ OAuth-only auth enforced │ │ │
│ │ │ ✓ Connects via socket only │ │ │
│ │ └──────────────┬───────────────────┘ │ │
│ │ │ │ │
│ │ │ Unix Socket │ │
│ │ │ /run/claude.sock │ │
│ │ ▼ │ │
│ │ ┌───────────────────────────────────────┐ │ │
│ │ │ Auth Proxy Sidecar │ │ │
│ │ │ (managed by IT) │ │ │
│ │ │ │ │ │
│ │ │ ✅ Validates OAuth token │ │ │
│ │ │ ✅ Injects org-level credentials │ │ │
│ │ │ ✅ Logs all API calls │ │ │
│ │ │ ✅ Enforces rate limits │ │ │
│ │ │ ✅ Routes to enterprise provider │ │ │
│ │ └───────────────┬───────────────────────┘ │ │
│ │ │ │ │
│ └──────────────────┼────────────────────────────┘ │
│ │ HTTPS │
└─────────────────────┼─────────────────────────────────┘
│
▼
┌────────────────────────┐
│ Anthropic API │
│ (or Bedrock/Vertex) │
└────────────────────────┘

Benefits:
✅ Zero-trust: Worker process cannot access credentials
✅ Auditability: All API calls logged at proxy level
✅ Multi-tenant isolation: Per-org credentials at proxy
✅ Simplified rotation: Creds managed centrally
✅ Compliance: Proxy can enforce PII filtering
```

---

## Policy & Plugin Management

```
┌──────────────────────────────────────────────────────────────────────┐
│ ENTERPRISE PLUGIN & POLICY ENFORCEMENT │
└──────────────────────────────────────────────────────────────────────┘

Organization Admin configures:

┌────────────────────────────────────────────────────┐
│ /nfs/corporate/claude-plugins/ │
│ (CLAUDE_CODE_PLUGIN_SEED_DIR) │
│ │
│ ├── cache/ │
│ │ └── corporate-internal/ │
│ │ ├── security-scanner/1.0.0/ │
│ │ │ ├── package.json │
│ │ │ ├── plugin.json │
│ │ │ └── mcp-server/ │
│ │ └── compliance-agent/2.1.0/ │
│ │ │
│ └── known_marketplaces.json │
│ { │
│ "corporate-internal": { │
│ "source": "https://plugins.corp.com", │
│ "readonly": true │
│ } │
│ } │
└────────────────────────────────────────────────────┘

User's settings.json:

{
"policySettings": {
"strictKnownMarketplaces": ["corporate-internal"],
"blockedMarketplaces": ["community-untrusted"],
"managedPlugins": {
"security-scanner": {
"version": "1.0.0",
"enabled": true,
"__readonly": true // User cannot disable
}
}
},
"enabledPlugins": {
"security-scanner": true, // Locked by policy
"my-personal-plugin": false // User can control
}
}

Runtime enforcement:

User tries: `claude plugin disable security-scanner`
│
├─ Check if plugin is in managedPlugins
│ └─ YES
│
├─ Error: "Plugin 'security-scanner' is managed by policy and cannot be disabled"
│
└─ Operation blocked

User tries: `claude plugin marketplace add malicious --source evil.com`
│
├─ Check strictKnownMarketplaces
│ └─ "evil.com" not in allowlist
│
├─ Error: "Marketplace source blocked by enterprise policy"
│
└─ Operation blocked
```

---

## Data Flow Summary

```
┌─────────────────────────────────────────────────────────────────────┐
│ COMPLETE ENTERPRISE DATA FLOW │
└─────────────────────────────────────────────────────────────────────┘

1. User Authentication
└─ OAuth → organizationUuid + accessToken + role

2. Session Initialization
├─ Load org settings from API
├─ Check seat tier assignment
├─ Fetch credit balance & limits
└─ Apply managed settings (if enterprise tier)

3. Feature Gate Check (e.g., Fast Mode)
├─ Org level: Is feature enabled for org?
├─ Seat level: Does tier include feature?
├─ Member level: User's credit balance OK?
└─ Service level: Runtime constraints (network, provider)

4. API Request
├─ Route to provider (first-party / Bedrock / Vertex / Foundry)
├─ Deduct credits from member balance
├─ Track usage for billing
└─ Emit telemetry (if metrics_enabled)

5. Credit Exhaustion
├─ Switch to overage mode
├─ User sees warning
└─ If overage exhausted → disable features

6. Admin Request
├─ User requests limit increase
├─ Admin reviews in dashboard
└─ Approval → credits replenished

7. Audit & Compliance
├─ All API calls logged (if unix socket mode)
├─ Usage data sent to org admin dashboard
└─ Periodic reports for billing
```

---

## Key Integration Points

| System | Integrates With | Data Exchanged |
|--------|----------------|----------------|
| **Billing** | Credit system, Overage tracking, Admin requests | Credit balance, usage metrics, limit changes |
| **Access Control** | Org settings, Seat tiers, Member roles | Permission states, feature flags |
| **Enterprise Providers** | Org config, Unix socket proxy | Provider selection, credential routing |
| **Plugin Management** | Policy enforcement, Seed directory | Allowed marketplaces, managed plugins |
| **Telemetry** | Org metrics toggle, Usage tracking | Event streams, audit logs |
| **Admin Dashboard** | All systems | Consolidated view, approval workflows |

---

## Conclusion

Claude Code 2.1.74 implements a **fully-integrated enterprise SaaS architecture** with:

- ✅ **Multi-tenancy** at org/seat/member levels
- ✅ **Fine-grained access control** (4-tier permission checks)
- ✅ **Production billing system** (credits, overage, admin approval)
- ✅ **Enterprise-grade security** (Unix socket proxy, OAuth-only mode)
- ✅ **Policy governance** (plugin management, managed settings)
- ✅ **Scalable provider routing** (Bedrock, Vertex, Foundry)

All systems work together to provide **enterprise-ready Claude Code** for large organizations.

---
## enterprise-configuration.md

# Enterprise configuration

Administrators on Team or Enterprise plans can control Claude Desktop through system policies.

**Note:** Enterprise policy controls at the user-machine level will override the in-app **[allowlist](https://support.claude.com/en/articles/12592343-enabling-and-using-the-desktop-extension-allowlist)**. If you want to use the allowlist, ensure `isDesktopExtensionEnabled` and `isDesktopExtensionDirectoryEnabled` are not set to "false" so the allowlist can populate the available registry.

------------------------------------------------------------------------

## macOS Enterprise Configuration

Deploy configuration settings through your MDM solution using configuration profiles. Claude Desktop reads preferences from the domain \`com.anthropic.claudefordesktop\`. Use your MDM tool (Jamf Pro, Kandji, Microsoft Intune) to deploy configuration profiles to target machines or user groups. Configuration profiles allow you to manage Claude Desktop settings centrally without user intervention.

**Configuration profile tools:**

- Built-in MDM profile editors (Jamf Pro, Kandji, Intune)

- **[ProfileCreator](https://github.com/profileCreator/ProfileCreator/)** - Profile management

- **[iMazing Profile Editor](https://imazing.com/profile-editor)** - Configuration profiles

------------------------------------------------------------------------

## Windows Enterprise Configuration

Deploy configuration settings through your enterprise management solution using **[Group Policy](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/policy/group-policy-objects)** or Intune policies. Settings can be configured at machine-wide (HKLM) or per-user (HKCU) level. Machine-level settings take priority over user-level settings when both are configured.

```powershell
# Set machine-wide settings (recommended)
New-Item -Path "HKLM:\SOFTWARE\Policies\Claude" -Force
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "disableAutoUpdates" -Value 0 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "autoUpdaterEnforcementHours" -Value 72 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "isDesktopExtensionEnabled" -Value 1 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "isDesktopExtensionDirectoryEnabled" -Value 1 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "isLocalDevMcpEnabled" -Value 1 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Claude" -Name "isClaudeCodeForDesktopEnabled" -Value 1 -Type DWord
```

------------------------------------------------------------------------

## Enterprise Policy Options

[TABLE]

---
## enterprise-providers-changes.md

# Enterprise Providers Changes: 2.1.59 → 2.1.70

## Overview

2.1.70 adds **Microsoft Foundry** as a third enterprise provider, making Claude Code
work across three hyperscaler platforms:

```
┌─────────────────────────────────┐
│ Claude Code CLI │
└────────────┬────────────────────┘
│ provider selection
┌────────────────────┼────────────────────────┐
│ │ │
┌─────────▼──────────┐ ┌───────▼───────┐ ┌─────────────▼────────────────────┐
│ AWS Bedrock │ │ Google Vertex │ │ Microsoft Foundry │ ← NEW
│ CLAUDE_CODE_USE_ │ │ AI (exists) │ │ CLAUDE_CODE_USE_FOUNDRY │
│ BEDROCK │ └───────────────┘ │ + Azure AD Auth │
│ + IAM/STS chain │ │ + FOUNDRY_RESOURCE │
│ + SSO support │ │ │
└────────────────────┘ └──────────────────────────────────┘
```

## Microsoft Foundry (New)

### Authentication Flow
```
CLAUDE_CODE_USE_FOUNDRY=true
→ FoundryClient(baseURL=ANTHROPIC_FOUNDRY_BASE_URL,
apiKey=ANTHROPIC_FOUNDRY_API_KEY,
resource=ANTHROPIC_FOUNDRY_RESOURCE)
→ DefaultAzureCredential (MSAL / Azure AD)
OR
CLAUDE_CODE_SKIP_FOUNDRY_AUTH=true → empty credential
```

### Restrictions
- Fast mode unavailable: "Fast mode is not available on Bedrock, Vertex, or Foundry"
- Telemetry disabled when Foundry active
- Feedback command disabled when Foundry active

### Model naming (inferred)
The `foundry` slot in the model map (e.g., `sonnet37.foundry`) likely uses
Azure-specific model deployment names, not claude-* IDs.

## AWS Bedrock Expansion

### New Headers (2.1.70 only)
| Header | Purpose |
|--------|---------|
| `X-Amzn-Bedrock-GuardrailIdentifier` | AWS Guardrails policy ID |
| `X-Amzn-Bedrock-GuardrailVersion` | Guardrails version |
| `X-Amzn-Bedrock-Service-Tier` | Service tier selection |
| `X-Amzn-Bedrock-PerformanceConfig-Latency` | Latency optimization |
| `X-Amzn-Bedrock-Trace` | Request tracing |

### New Bedrock APIs
- **Reranking**: `VectorSearchBedrockRerankingConfiguration`, `BEDROCK_RERANKING_MODEL`
- **Inference Profiles**: `ListInferenceProfilesCommand`, `GetInferenceProfileCommand`
- **Prompt Routers**: `paginateListPromptRouters`
- **Provisioned Throughput**: `paginateListProvisionedModelThroughputs`

### New Auth Options
- `AWS_BEARER_TOKEN_BEDROCK` — bearer token (simpler than IAM role chain)
- `CLAUDE_CODE_SKIP_BEDROCK_AUTH` — skip auth (for testing/custom endpoints)
- `ANTHROPIC_BEDROCK_BASE_URL` — custom Bedrock endpoint

## Model Routing Map (2.1.70)

```javascript
// Each model has 4 provider variants
const modelMap = {
haiku35: { firstParty: "claude-haiku-3-5-...", bedrock: "...", vertex: "...", foundry: "..." },
haiku45: { firstParty: "claude-haiku-4-5-...", ... },
sonnet35: { ... },
sonnet37: { firstParty: "claude-3-7-sonnet-20250219", bedrock: "...", vertex: "claude-3-7-sonnet@20250219", foundry: "claude-3-7-sonnet" },
sonnet40: { ... },
sonnet45: { ... }, // NEW
sonnet46: { ... }, // NEW — current model (claude-sonnet-4-6)
opus40: { ... },
opus41: { ... }, // NEW
opus45: { ... }, // NEW
opus46: { ... }, // NEW
}
```

---
## find-and-join-a-team-or-enterprise-organization.md

4. Find and join a Team or Enterprise organization

# Find and join a Team or Enterprise organization

Organization discovery allows you to find and join your company's existing Team or Enterprise plan organization when you start the sign-up flow with a work email address. Instead of creating a separate personal account, you can request to join—or be added automatically—depending on your organization's configuration.

**Note:** Organization discovery is only available for organizations that don't have **[single sign-on (SSO) enabled](../21-Account-Support/setting-up-single-sign-on-sso.md)**. If your organization uses SSO, your existing provisioning settings remain in effect.

------------------------------------------------------------------------

## Admin setup

### Enable discoverability

Admins and above can manage organization discovery from **[Organization settings \> Identity and access](https://claude.ai/admin-settings/identity)**.

- **New organizations:**

- **Team plans:** Discoverability is on by default. Admins see the option during plan onboarding with it pre-selected.

- **Enterprise plans:** Discoverability is off by default. Admins will see the option disabled on the Identity and access page.

- **Existing organizations:** Discoverability is off by default. Admins can turn it on from settings at any time.

To enable discoverability:

1. Log in as an Admin, Owner, Primary Owner.

2. Navigate to **[Organization settings \> Identity and access](https://claude.ai/admin-settings/identity)**.

3. Your organization’s domains are listed at the top of the page.

4. Find the domain you want users to search for and click the toggle under **Discoverable**.

5. Find **New member approval** under **Global access settings** and choose either “Approve automatically” or “Require admin approval.”

### Configure allowed domains

Admins can specify which email domains are allowed to discover and join the organization by clicking “+ Add domain” under **Domains** on the Identity and access page. The organization owner’s domain will appear on the **Domains** list automatically, but admins can configure additional allowed domains by adding them here, verifying them, and toggling **Discoverable** on. Personal email domains (like Gmail) and .edu domains can't be added to the allowed list.

### Choose an approval mode

Admins select how join requests are handled:

**Instant approval:** Users are added to the organization’s lowest available seat tier automatically when they ask to join. Billing begins as soon as a user joins—if the organization has no available seats, billing auto-expands and a new seat is purchased immediately.

**Request + approve:** The admin reviews and approves each join request individually. Users aren't added to the organization until the admin approves. Billing begins when the request is approved—if no seats are available at that point, a new seat is purchased.

This approval mode also applies to invitations sent by existing members of your organization. For additional details, see **[Manage members on Team and Enterprise plans](../17-Billing-Plans/managing-members-on-team-and-enterprise-plans.md)**.

------------------------------------------------------------------------

## How to find and join an organization

When someone signs up for Claude with a work email address that matches a discoverable organization, they'll see the option to join during the signup flow. They can choose to join or continue with a personal account.

- If the organization uses **instant approval**, they're added right away.

- If the organization uses **request + approve**, a request is sent to the admin. The requester can choose to continue with a personal account (as long as "Restrict organization creation" is disabled) until the request is approved or denied.

If multiple organizations share the same email domain and are all discoverable, users will see all of them and can choose which one to join.

------------------------------------------------------------------------

## Other ways to join an organization

In addition to organization discovery, there are a few other ways to join a Team or Enterprise organization:

- **Invite link:** Your admin may share an invite link that lets you join directly. See **[Join an organization via invite link](https://support.claude.com/en/articles/13776697-join-an-organization-via-invite-link#h_af9f6b7825)**.

- **Note:** If the invite link has been disabled or regenerated by your admin, it will no longer work. Ask your admin to share a new link.

- **Email invitation:** An admin or existing member of the organization may send you an email invitation to join.

- **Admin invitation:** An admin can add you directly from admin settings. See **[Manage members on Team and Enterprise plans](../17-Billing-Plans/managing-members-on-team-and-enterprise-plans.md)**.

------------------------------------------------------------------------

## SSO and organization discovery

Organization discovery is not available for organizations with single sign-on enabled. If your organization uses SSO, the feature doesn't apply—your existing provisioning settings (including any just-in-time provisioning) remain unchanged.

If you'd like to enable organization discovery, SSO must be turned off first.

---
## getting-started-with-claude-for-enterprise.md

# Getting started with Claude Enterprise

Resources for new enterprise customers.

Welcome to Claude Enterprise! Our Customer Success team has put together the following guides to jumpstart your Claude for Enterprise journey with best practices, practical guidance, launch checklists, and more.

- [Getting started guide for admin setup](https://cdn.sanity.io/files/4zrzovbb/website/f445a7cc34957e7c145ffb2937af85916356e8da.pdf)

- [Getting started guide for end users](https://cdn.sanity.io/files/4zrzovbb/website/97c4b90b0af9ad8b8332980010157044d58b40ba.pdf)

If you're responsible for rolling out Claude to your organization, you may also like this [course](https://anthropic.skilljar.com/driving-enterprise-adoption-of-claude) in Anthropic Academy, designed for project owners like you!

## Additional support

Anthropic has services partners (advisory, training, change management, MCP development) available who can help provide additional support. If you'd like to discuss further, please submit [this interest form](https://forms.gle/ubnR5f7q5E71ECR79). For requests to connect with our Sales team, please contact [\[email protected\]](/cdn-cgi/l/email-protection#75061419100635141b011d071a051c165b161a18)

---
## iam.md

> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Identity and Access Management

> Learn how to configure user authentication, authorization, and access controls for Claude Code in your organization.

## Authentication methods

Setting up Claude Code requires access to Anthropic models. For teams, you can set up Claude Code access in one of these ways:

* [Claude for Teams or Enterprise](/en/setup#for-teams-and-organizations) (recommended)
* [Claude Console with team billing](/en/setup#for-teams-and-organizations)
* [Amazon Bedrock](../02-Claude-Code-CLI/claude-code-on-amazon-bedrock-claude-code-docs.md)
* [Google Vertex AI](../02-Claude-Code-CLI/claude-code-on-google-vertex-ai-claude-code-docs.md)
* [Microsoft Foundry](../02-Claude-Code-CLI/claude-code-on-microsoft-foundry-claude-code-docs.md)

### Claude for Teams or Enterprise (recommended)

[Claude for Teams](https://claude.com/pricing#team-&-enterprise) and [Claude for Enterprise](https://anthropic.com/contact-sales) provide the best experience for organizations using Claude Code. Team members get access to both Claude Code and Claude on the web with centralized billing and team management.

* **Claude for Teams**: Self-service plan with collaboration features, admin tools, and billing management. Best for smaller teams.
* **Claude for Enterprise**: Adds SSO, domain capture, role-based permissions, compliance API, and managed policy settings for organization-wide Claude Code configurations. Best for larger organizations with security and compliance requirements.

**To set up Claude Code access:**

1. Subscribe to [Claude for Teams](https://claude.com/pricing#team-&-enterprise) or contact sales for [Claude for Enterprise](https://anthropic.com/contact-sales)
2. Invite team members from the admin dashboard
3. Team members install Claude Code and log in with their Claude.ai accounts

### Claude Console authentication

For organizations that prefer API-based billing, you can set up access through the Claude Console.

**To set up Claude Code access for your team via Claude Console:**

1. Use your existing Claude Console account or create a new Claude Console account
2. You can add users through either method below:
* Bulk invite users from within the Console (Console -> Settings -> Members -> Invite)
* [Set up SSO](../21-Account-Support/setting-up-single-sign-on-sso.md)
3. When inviting users, they need one of the following roles:
* "Claude Code" role means users can only create Claude Code API keys
* "Developer" role means users can create any kind of API key
4. Each invited user needs to complete these steps:
* Accept the Console invite
* [Check system requirements](/en/setup#system-requirements)
* [Install Claude Code](/en/setup#installation)
* Login with Console account credentials

### Cloud provider authentication

**To set up Claude Code access for your team via Bedrock, Vertex, or Azure:**

1. Follow the [Bedrock docs](../02-Claude-Code-CLI/claude-code-on-amazon-bedrock-claude-code-docs.md), [Vertex docs](../02-Claude-Code-CLI/claude-code-on-google-vertex-ai-claude-code-docs.md), or [Microsoft Foundry docs](../02-Claude-Code-CLI/claude-code-on-microsoft-foundry-claude-code-docs.md)
2. Distribute the environment variables and instructions for generating cloud credentials to your users. Read more about how to [manage configuration here](../02-Claude-Code-CLI/claude-code-settings-claude-code-docs-d4420b4b52.md).
3. Users can [install Claude Code](/en/setup#installation)

## Access control and permissions

We support fine-grained permissions so that you're able to specify exactly what the agent is allowed to do (e.g. run tests, run linter) and what it is not allowed to do (e.g. update cloud infrastructure). These permission settings can be checked into version control and distributed to all developers in your organization, as well as customized by individual developers.

### Permission system

Claude Code uses a tiered permission system to balance power and safety:

### Configuring permissions

You can view & manage Claude Code's tool permissions with `/permissions`. This UI lists all permission rules and the settings.json file they are sourced from.

* **Allow** rules let Claude Code use the specified tool without manual approval.
* **Ask** rules prompt for confirmation whenever Claude Code tries to use the specified tool.
* **Deny** rules prevent Claude Code from using the specified tool.

Rules are evaluated in order: **deny → ask → allow**. The first matching rule wins, so deny rules always take precedence.

* **Additional directories** extend Claude's file access to directories beyond the initial working directory.
* **Default mode** controls Claude's permission behavior when encountering new requests.

Permission rules use the format: `Tool` or `Tool(optional-specifier)`

A rule that is just the tool name matches any use of that tool. For example, adding `Bash` to the allow list allows Claude Code to use the Bash tool without requiring user approval. `Bash(*)` is equivalent to `Bash` and can be used interchangeably.

<Note>
For a quick reference on permission rule syntax including wildcards, see [Permission rule syntax](/en/settings#permission-rule-syntax) in the settings documentation.
</Note>

#### Permission modes

Claude Code supports several permission modes that can be set as the `defaultMode` in [settings files](/en/settings#settings-files):

| Mode | Description |
| :------------------ | :------------------------------------------------------------------------------------------------------------------------ |
| `default` | Standard behavior - prompts for permission on first use of each tool |
| `acceptEdits` | Automatically accepts file edit permissions for the session |
| `plan` | Plan Mode - Claude can analyze but not modify files or execute commands |
| `dontAsk` | Auto-denies tools unless pre-approved via `/permissions` or [`permissions.allow`](/en/settings#permission-settings) rules |
| `bypassPermissions` | Skips all permission prompts (requires safe environment - see warning below) |

#### Working directories

By default, Claude has access to files in the directory where it was launched. You can extend this access:

* **During startup**: Use `--add-dir <path>` CLI argument
* **During session**: Use `/add-dir` command
* **Persistent configuration**: Add to `additionalDirectories` in [settings files](/en/settings#settings-files)

Files in additional directories follow the same permission rules as the original working directory - they become readable without prompts, and file editing permissions follow the current permission mode.

#### Tool-specific permission rules

Some tools support more fine-grained permission controls:

**Bash**

Bash permission rules support wildcard matching with `*`. Wildcards can appear at any position in the command, including at the beginning, middle, or end:

* `Bash(npm run build)` Matches the exact Bash command `npm run build`
* `Bash(npm run test *)` Matches Bash commands starting with `npm run test`
* `Bash(npm *)` Matches any command starting with `npm ` (e.g., `npm install`, `npm run build`)
* `Bash(* install)` Matches any command ending with ` install` (e.g., `npm install`, `yarn install`)
* `Bash(git * main)` Matches commands like `git checkout main`, `git merge main`
* `Bash(* --help *)` Matches any command with `--help` followed by additional arguments

When `*` appears at the end with a space before it (like `Bash(ls *)`), it enforces a word boundary, requiring the prefix to be followed by a space or end-of-string. For example, `Bash(ls *)` matches `ls -la` but not `lsof`. In contrast, `Bash(ls*)` without a space matches both `ls -la` and `lsof` because there's no word boundary constraint. The legacy `:*` suffix syntax is equivalent to ` *` but is deprecated.

<Tip>
Claude Code is aware of shell operators (like `&&`) so a prefix match rule like `Bash(safe-cmd *)` won't give it permission to run the command `safe-cmd && other-cmd`
</Tip>

<Warning>
Important limitations of Bash permission patterns:

1. The space before `*` matters: `Bash(ls *)` matches `ls -la` but not `lsof`, while `Bash(ls*)` matches both
2. The `*` wildcard can appear at any position and matches any sequence of characters
3. Patterns like `Bash(curl http://github.com/ *)` can be bypassed in many ways:
* Options before URL: `curl -X GET http://github.com/...` won't match
* Different protocol: `curl https://github.com/...` won't match
* Redirects: `curl -L http://bit.ly/xyz` (redirects to github)
* Variables: `URL=http://github.com && curl $URL` won't match
* Extra spaces: `curl http://github.com` won't match

For more reliable URL filtering, consider:

* **Restrict Bash network tools**: Use deny rules to block `curl`, `wget`, and similar commands, then use the WebFetch tool with `WebFetch(domain:github.com)` permission for allowed domains
* **Use PreToolUse hooks**: Implement a hook that validates URLs in Bash commands and blocks disallowed domains
* Instructing Claude Code about your allowed curl patterns via CLAUDE.md

Note that using WebFetch alone does not prevent network access. If Bash is allowed, Claude can still use `curl`, `wget`, or other tools to reach any URL.
</Warning>

**Read & Edit**

`Edit` rules apply to all built-in tools that edit files. Claude will make a best-effort attempt to apply `Read` rules to all built-in tools that read files like Grep and Glob.

Read & Edit rules both follow the [gitignore](https://git-scm.com/docs/gitignore) specification with four distinct pattern types:

| Pattern | Meaning | Example | Matches |
| ------------------ | -------------------------------------- | -------------------------------- | ---------------------------------- |
| `//path` | **Absolute** path from filesystem root | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |
| `~/path` | Path from **home** directory | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |
| `/path` | Path **relative to settings file** | `Edit(/src/**/*.ts)` | `<settings file path>/src/**/*.ts` |
| `path` or `./path` | Path **relative to current directory** | `Read(*.env)` | `<cwd>/*.env` |

<Warning>
A pattern like `/Users/alice/file` is NOT an absolute path - it's relative to your settings file! Use `//Users/alice/file` for absolute paths.
</Warning>

* `Edit(/docs/**)` - Edits in `<project>/docs/` (NOT `/docs/`!)
* `Read(~/.zshrc)` - Reads your home directory's `.zshrc`
* `Edit(//tmp/scratch.txt)` - Edits the absolute path `/tmp/scratch.txt`
* `Read(src/**)` - Reads from `<current-directory>/src/`

<Note>
In gitignore patterns, `*` matches files in a single directory while `**` matches recursively across directories. To allow all file access, use just the tool name without parentheses: `Read`, `Edit`, or `Write`.
</Note>

**WebFetch**

* `WebFetch(domain:example.com)` Matches fetch requests to example.com

**MCP**

* `mcp__puppeteer` Matches any tool provided by the `puppeteer` server (name configured in Claude Code)
* `mcp__puppeteer__*` Wildcard syntax that also matches all tools from the `puppeteer` server
* `mcp__puppeteer__puppeteer_navigate` Matches the `puppeteer_navigate` tool provided by the `puppeteer` server

**Task (Subagents)**

Use `Task(AgentName)` rules to control which [subagents](../09-Agents-Patterns/create-custom-subagents-claude-code-docs-7dc93e85c0.md) Claude can use:

* `Task(Explore)` Matches the Explore subagent
* `Task(Plan)` Matches the Plan subagent
* `Task(Verify)` Matches the Verify subagent

Add these rules to the `deny` array in your [settings](/en/settings#permission-settings) or use the `--disallowedTools` CLI flag to disable specific agents. For example, to disable the Explore agent:

```json theme={null}
{
"permissions": {
"deny": ["Task(Explore)"]
}
}
```

### Additional permission control with hooks

[Claude Code hooks](../07-Hooks/automate-workflows-with-hooks-claude-code-docs-e843f93261.md) provide a way to register custom shell commands to perform permission evaluation at runtime. When Claude Code makes a tool call, PreToolUse hooks run before the permission system runs, and the hook output can determine whether to approve or deny the tool call in place of the permission system.

### Managed settings

For organizations that need centralized control over Claude Code configuration, administrators can deploy `managed-settings.json` files to [system directories](/en/settings#settings-files). These policy files follow the same format as regular settings files and cannot be overridden by user or project settings.

### Settings precedence

When multiple settings sources exist, they are applied in the following order (highest to lowest precedence):

1. Managed settings (`managed-settings.json`)
2. Command line arguments
3. Local project settings (`.claude/settings.local.json`)
4. Shared project settings (`.claude/settings.json`)
5. User settings (`~/.claude/settings.json`)

This hierarchy ensures that organizational policies are always enforced while still allowing flexibility at the project and user levels where appropriate.

## Credential management

Claude Code securely manages your authentication credentials:

* **Storage location**: On macOS, API keys, OAuth tokens, and other credentials are stored in the encrypted macOS Keychain.
* **Supported authentication types**: Claude.ai credentials, Claude API credentials, Azure Auth, Bedrock Auth, and Vertex Auth.
* **Custom credential scripts**: The [`apiKeyHelper`](/en/settings#available-settings) setting can be configured to run a shell script that returns an API key.
* **Refresh intervals**: By default, `apiKeyHelper` is called after 5 minutes or on HTTP 401 response. Set `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` environment variable for custom refresh intervals.

---
## legal-and-compliance.md

> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Legal and compliance

> Legal agreements, compliance certifications, and security information for Claude Code.

## Legal agreements

### License

Your use of Claude Code is subject to:

* [Commercial Terms](https://www.anthropic.com/legal/commercial-terms) - for Team, Enterprise, and Claude API users
* [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) - for Free, Pro, and Max users

### Commercial agreements

Whether you're using the Claude API directly (1P) or accessing it through AWS Bedrock or Google Vertex (3P), your existing commercial agreement will apply to Claude Code usage, unless we've mutually agreed otherwise.

## Compliance

### Healthcare compliance (BAA)

If a customer has a Business Associate Agreement (BAA) with us, and wants to use Claude Code, the BAA will automatically extend to cover Claude Code if the customer has executed a BAA and has Zero Data Retention (ZDR) activated. The BAA will be applicable to that customer's API traffic flowing through Claude Code.

## Security and trust

### Trust and safety

You can find more information in the [Anthropic Trust Center](https://trust.anthropic.com) and [Transparency Hub](https://www.anthropic.com/transparency).

### Security vulnerability reporting

Anthropic manages our security program through HackerOne. [Use this form to report vulnerabilities](https://hackerone.com/anthropic-vdp/reports/new?type=team\&report_type=vulnerability).

***

---
## llm-gateway-configuration-claude-code-docs-7a1628ac88.md

# LLM gateway configuration

Learn how to configure Claude Code to work with LLM gateway solutions. Covers gateway requirements, authentication configuration, model selection, and provider-specific endpoint setup.

LLM gateways provide a centralized proxy layer between Claude Code and model providers, often providing:

- **Centralized authentication** - Single point for API key management
- **Usage tracking** - Monitor usage across teams and projects
- **Cost controls** - Implement budgets and rate limits
- **Audit logging** - Track all model interactions for compliance
- **Model routing** - Switch between providers without code changes

[](#gateway-requirements)

Gateway requirements

For an LLM gateway to work with Claude Code, it must meet the following requirements: **API format** The gateway must expose to clients at least one of the following API formats:

1. **Anthropic Messages**: `/v1/messages`, `/v1/messages/count_tokens`
- Must forward request headers: `anthropic-beta`, `anthropic-version`
2. **Bedrock InvokeModel**: `/invoke`, `/invoke-with-response-stream`
- Must preserve request body fields: `anthropic_beta`, `anthropic_version`
3. **Vertex rawPredict**: `:rawPredict`, `:streamRawPredict`, `/count-tokens:rawPredict`
- Must forward request headers: `anthropic-beta`, `anthropic-version`

Failure to forward headers or preserve body fields may result in reduced functionality or inability to use Claude Code features.

Claude Code determines which features to enable based on the API format. When using the Anthropic Messages format with Bedrock or Vertex, you may need to set environment variable `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`.

**Request headers** Claude Code includes the following headers on every API request:

| Header | Description |
|:---|:---|
| `X-Claude-Code-Session-Id` | A unique identifier for the current Claude Code session. Proxies can use this to aggregate all API requests from a single session without parsing the request body. |

[](#configuration)

Configuration

[](#model-selection)

Model selection

By default, Claude Code will use standard model names for the selected API format. If you have configured custom model names in your gateway, use the environment variables documented in [Model configuration](/docs/en/model-config) to match your custom names.

[](#litellm-configuration)

LiteLLM configuration

LiteLLM PyPI versions 1.82.7 and 1.82.8 were compromised with credential-stealing malware. Do not install these versions. If you have already installed them:

- Remove the package
- Rotate all credentials on affected systems
- Follow the remediation steps in [BerriAI/litellm#24518](https://github.com/BerriAI/litellm/issues/24518)

LiteLLM is a third-party proxy service. Anthropic doesn’t endorse, maintain, or audit LiteLLM’s security or functionality. This guide is provided for informational purposes and may become outdated. Use at your own discretion.

[](#prerequisites)

Prerequisites

- Claude Code updated to the latest version
- LiteLLM Proxy Server deployed and accessible
- Access to Claude models through your chosen provider

[](#basic-litellm-setup)

Basic LiteLLM setup

**Configure Claude Code**:

[](#authentication-methods)

Authentication methods

##### Static API key

Simplest method using a fixed API key:

```python
# Set in environment
export ANTHROPIC_AUTH_TOKEN=sk-litellm-static-key

# Or in Claude Code settings
{
"env": {
"ANTHROPIC_AUTH_TOKEN": "sk-litellm-static-key"
}
}
```

This value will be sent as the `Authorization` header.

##### Dynamic API key with helper

For rotating keys or per-user authentication:

1. Create an API key helper script:

```python
#!/bin/bash
# ~/bin/get-litellm-key.sh

# Example: Fetch key from vault
vault kv get -field=api_key secret/litellm/claude-code

# Example: Generate JWT token
jwt encode \
--secret="${JWT_SECRET}" \
--exp="+1h" \
'{"user":"'${USER}'","team":"engineering"}'
```

2. Configure Claude Code settings to use the helper:

```python
{
"apiKeyHelper": "~/bin/get-litellm-key.sh"
}
```

3. Set token refresh interval:

```python
# Refresh every hour (3600000 ms)
export CLAUDE_CODE_API_KEY_HELPER_TTL_MS=3600000
```

This value will be sent as `Authorization` and `X-Api-Key` headers. The `apiKeyHelper` has lower precedence than `ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`.

[](#unified-endpoint-recommended)

Unified endpoint (recommended)

Using LiteLLM’s [Anthropic format endpoint](https://docs.litellm.ai/docs/anthropic_unified):

```python
export ANTHROPIC_BASE_URL=https://litellm-server:4000
```

**Benefits of the unified endpoint over pass-through endpoints:**

- Load balancing
- Fallbacks
- Consistent support for cost tracking and end-user tracking

[](#provider-specific-pass-through-endpoints-alternative)

Provider-specific pass-through endpoints (alternative)

##### Claude API through LiteLLM

Using [pass-through endpoint](https://docs.litellm.ai/docs/pass_through/anthropic_completion):

```python
export ANTHROPIC_BASE_URL=https://litellm-server:4000/anthropic
```

##### Amazon Bedrock through LiteLLM

Using [pass-through endpoint](https://docs.litellm.ai/docs/pass_through/bedrock):

```python
export ANTHROPIC_BEDROCK_BASE_URL=https://litellm-server:4000/bedrock
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export CLAUDE_CODE_USE_BEDROCK=1
```

##### Google Vertex AI through LiteLLM

Using [pass-through endpoint](https://docs.litellm.ai/docs/pass_through/vertex_ai):

```python
export ANTHROPIC_VERTEX_BASE_URL=https://litellm-server:4000/vertex_ai/v1
export ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
```

For more detailed information, refer to the [LiteLLM documentation](https://docs.litellm.ai/).

[](#additional-resources)

Additional resources

- [LiteLLM documentation](https://docs.litellm.ai/)
- [Claude Code settings](/docs/en/settings)
- [Enterprise network configuration](/docs/en/network-config)
- [Third-party integrations overview](/docs/en/third-party-integrations)

---
## migrate-your-organization-from-team-to-enterprise.md

4. Migrate your organization from Team to Enterprise

# Migrate your organization from Team to Enterprise

When upgrading from a Team plan to an Enterprise plan, we recommend you keep the same Team organization and follow the upgrade path to change it to Enterprise. This way your data (memberships/roles, conversations and projects) and settings will be preserved. If a you create a brand new Enterprise organization, then you'll need to set up everything from scratch.

## What's retained (same organization upgrade)

- All chat history and conversations

- Projects and shared content

- User memberships and roles

## Migrate from Team to Enterprise

You can migrate from a Team plan to a self-serve Enterprise plan by following these steps:

1. Navigate to **[claude.ai/upgrade](https://claude.ai/upgrade)** and click "Get Enterprise plan."

2. When prompted, choose "Upgrade an existing organization" and select your Team plan organization.

3. Add the number of seats needed for all your team members (Enterprise organizations have a 20 seat minimum).

4. Set a per-user spend limit and a starting usage balance for the whole team.

5. Your payment information will be saved from previous Team plan payments, but you can click the pencil icon to change it if needed.

1. We only support credit card payments for self-serve Enterprise plans. For more information, see **[Self-serve vs. sales-assisted Enterprise](../17-Billing-Plans/what-is-the-enterprise-plan.md#h_3058c781c5)**.

6. Review your order summary and click "Confirm upgrade."

**Important:** Migrating an organization from Team to Enterprise via this pathway is not reversible; please ensure that an Enterprise plan is the right fit for your organization before initiating this change.

## Seat assignment

During migration, some users may appear as "Unassigned" rather than being automatically mapped to seat tiers. Admins should verify all users have correct seat assignments after the cutover.

For detailed guidance, refer to **[Purchasing and managing seats on Enterprise plans](../17-Billing-Plans/purchasing-and-managing-seats-on-enterprise-plans.md)**.

## SSO and identity setup timeline

- **Domain verification (DNS):** Allow 24–48 hours for DNS changes to propagate globally, though many changes take effect within 10 minutes.

- **SCIM provisioning sync:** Microsoft Entra ID pushes changes approximately every 40 minutes. Okta syncs more frequently.

For detailed setup instructions, refer to **[Setting up single sign-on (SSO)](../21-Account-Support/setting-up-single-sign-on-sso.md)** and **[Setting up JIT or SCIM provisioning](setting-up-jit-or-scim-provisioning.md).**

**Note:** Once you turn on SSO, existing users will be forced to log out and log back in.

## Billing and usage configuration

For usage-based Enterprise plans, usage is billed based on actual consumption. For more detailed information, refer to **[How am I billed for my Enterprise plan?](../17-Billing-Plans/how-am-i-billed-for-my-enterprise-plan.md)**

If you had purchased extra usage for your Team plan, any unused credits will roll over and become available on your new usage-based Enterprise plan.

## Provisioning process

On the start date, you'll be provisioned and able to use the new features by the end of the day. After initial setup, Owners and Primary Owners can self-serve additional seats by navigating to **[Organization settings \> Organization](https://claude.ai/admin-settings/organization)** and clicking "Manage" under **Total seats**.

## Helpful resources

- **[Set up single sign-on (SSO)](../21-Account-Support/set-up-single-sign-on-sso.md)**

- **[Set up JIT or SCIM provisioning](set-up-jit-or-scim-provisioning.md)**

- **[Purchase and manage seats on Enterprise plans](../17-Billing-Plans/purchase-and-manage-seats-on-enterprise-plans.md)**

- **[Manage members on Team and Enterprise plans](../17-Billing-Plans/manage-members-on-team-and-enterprise-plans.md)**

- **[Enterprise billing information](../17-Billing-Plans/how-am-i-billed-for-my-enterprise-plan.md)**

- **[Use Claude Code with your Team or Enterprise plan](../17-Billing-Plans/use-claude-code-with-your-team-or-enterprise-plan.md)**

---
## monitoring-claude-code-docs-72c46f3dc8.md

# Monitoring

Learn how to enable and configure OpenTelemetry for Claude Code.

Track Claude Code usage, costs, and tool activity across your organization by exporting telemetry data through OpenTelemetry (OTel). Claude Code exports metrics as time series data via the standard metrics protocol, events via the logs/events protocol, and optionally distributed traces via the [traces protocol](#traces-beta). Configure your metrics, logs, and traces backends to match your monitoring requirements.

[](#quick-start)

Quick start

Configure OpenTelemetry using environment variables:

```python
# 1. Enable telemetry
export CLAUDE_CODE_ENABLE_TELEMETRY=1

# 2. Choose exporters (both are optional - configure only what you need)
export OTEL_METRICS_EXPORTER=otlp # Options: otlp, prometheus, console, none
export OTEL_LOGS_EXPORTER=otlp # Options: otlp, console, none

# 3. Configure OTLP endpoint (for OTLP exporter)
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# 4. Set authentication (if required)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"

# 5. For debugging: reduce export intervals
export OTEL_METRIC_EXPORT_INTERVAL=10000 # 10 seconds (default: 60000ms)
export OTEL_LOGS_EXPORT_INTERVAL=5000 # 5 seconds (default: 5000ms)

# 6. Run Claude Code
claude
```

The default export intervals are 60 seconds for metrics and 5 seconds for logs. During setup, you may want to use shorter intervals for debugging purposes. Remember to reset these for production use.

For full configuration options, see the [OpenTelemetry specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options).

[](#administrator-configuration)

Administrator configuration

Administrators can configure OpenTelemetry settings for all users through the [managed settings file](/docs/en/settings#settings-files). This allows for centralized control of telemetry settings across an organization. See the [settings precedence](/docs/en/settings#settings-precedence) for more information about how settings are applied. Example managed settings configuration:

```python
{
"env": {
"CLAUDE_CODE_ENABLE_TELEMETRY": "1",
"OTEL_METRICS_EXPORTER": "otlp",
"OTEL_LOGS_EXPORTER": "otlp",
"OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
"OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
"OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
}
}
```

Managed settings can be distributed via MDM (Mobile Device Management) or other device management solutions. Environment variables defined in the managed settings file have high precedence and cannot be overridden by users.

[](#configuration-details)

Configuration details

[](#common-configuration-variables)

Common configuration variables

| Environment Variable | Description | Example Values |
|----|----|----|
| `CLAUDE_CODE_ENABLE_TELEMETRY` | Enables telemetry collection (required) | `1` |
| `OTEL_METRICS_EXPORTER` | Metrics exporter types, comma-separated. Use `none` to disable | `console`, `otlp`, `prometheus`, `none` |
| `OTEL_LOGS_EXPORTER` | Logs/events exporter types, comma-separated. Use `none` to disable | `console`, `otlp`, `none` |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | Protocol for OTLP exporter, applies to all signals | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint for all signals | `http://localhost:4317` |
| `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` | Protocol for metrics, overrides general setting | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | OTLP metrics endpoint, overrides general setting | `http://localhost:4318/v1/metrics` |
| `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL` | Protocol for logs, overrides general setting | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP logs endpoint, overrides general setting | `http://localhost:4318/v1/logs` |
| `OTEL_EXPORTER_OTLP_HEADERS` | Authentication headers for OTLP | `Authorization=Bearer token` |
| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` | Client key for mTLS authentication | Path to client key file |
| `OTEL_EXPORTER_OTLP_METRICS_CLIENT_CERTIFICATE` | Client certificate for mTLS authentication | Path to client cert file |
| `OTEL_METRIC_EXPORT_INTERVAL` | Export interval in milliseconds (default: 60000) | `5000`, `60000` |
| `OTEL_LOGS_EXPORT_INTERVAL` | Logs export interval in milliseconds (default: 5000) | `1000`, `10000` |
| `OTEL_LOG_USER_PROMPTS` | Enable logging of user prompt content (default: disabled) | `1` to enable |
| `OTEL_LOG_TOOL_DETAILS` | Enable logging of tool parameters and input arguments in tool events and trace span attributes: Bash commands, MCP server and tool names, skill names, and tool input. Also enables custom, plugin, and MCP command names on `user_prompt` events (default: disabled) | `1` to enable |
| `OTEL_LOG_TOOL_CONTENT` | Enable logging of tool input and output content in span events (default: disabled). Requires [tracing](#traces-beta). Content is truncated at 60 KB | `1` to enable |
| `OTEL_LOG_RAW_API_BODIES` | Emit the full Anthropic Messages API request and response JSON as `api_request_body` / `api_response_body` log events (default: disabled). Bodies include the entire conversation history. Enabling this implies consent to everything `OTEL_LOG_USER_PROMPTS`, `OTEL_LOG_TOOL_DETAILS`, and `OTEL_LOG_TOOL_CONTENT` would reveal | `1` for inline bodies truncated at 60 KB, or `file:<dir>` for untruncated bodies on disk with a `body_ref` pointer in the event |
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Metrics temporality preference (default: `delta`). Set to `cumulative` if your backend expects cumulative temporality | `delta`, `cumulative` |
| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | Interval for refreshing dynamic headers (default: 1740000ms / 29 minutes) | `900000` |

[](#metrics-cardinality-control)

Metrics cardinality control

The following environment variables control which attributes are included in metrics to manage cardinality:

| Environment Variable | Description | Default Value | Example to Disable |
|----|----|----|----|
| `OTEL_METRICS_INCLUDE_SESSION_ID` | Include session.id attribute in metrics | `true` | `false` |
| `OTEL_METRICS_INCLUDE_VERSION` | Include app.version attribute in metrics | `false` | `true` |
| `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | Include user.account_uuid and user.account_id attributes in metrics | `true` | `false` |

These variables help control the cardinality of metrics, which affects storage requirements and query performance in your metrics backend. Lower cardinality generally means better performance and lower storage costs but less granular data for analysis.

[](#traces-beta)

Traces (beta)

Distributed tracing exports spans that link each user prompt to the API requests and tool executions it triggers, so you can view a full request as a single trace in your tracing backend. Tracing is off by default. To enable it, set both `CLAUDE_CODE_ENABLE_TELEMETRY=1` and `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, then set `OTEL_TRACES_EXPORTER` to choose where spans are sent. Traces reuse the [common OTLP configuration](#common-configuration-variables) for endpoint, protocol, and headers.

| Environment Variable | Description | Example Values |
|----|----|----|
| `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | Enable span tracing (required). `ENABLE_ENHANCED_TELEMETRY_BETA` is also accepted | `1` |
| `OTEL_TRACES_EXPORTER` | Traces exporter types, comma-separated. Use `none` to disable | `console`, `otlp`, `none` |
| `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` | Protocol for traces, overrides `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`, `http/json`, `http/protobuf` |
| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | OTLP traces endpoint, overrides `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://localhost:4318/v1/traces` |
| `OTEL_TRACES_EXPORT_INTERVAL` | Span batch export interval in milliseconds (default: 5000) | `1000`, `10000` |

Spans redact user prompt text, tool input details, and tool content by default. Set `OTEL_LOG_USER_PROMPTS=1`, `OTEL_LOG_TOOL_DETAILS=1`, and `OTEL_LOG_TOOL_CONTENT=1` to include them. When tracing is active, Bash and PowerShell subprocesses automatically inherit a `TRACEPARENT` environment variable containing the W3C trace context of the active tool execution span. This lets any subprocess that reads `TRACEPARENT` parent its own spans under the same trace, enabling end-to-end distributed tracing through scripts and commands that Claude runs. In Agent SDK and non-interactive sessions started with `-p`, Claude Code also reads `TRACEPARENT` and `TRACESTATE` from its own environment when starting each interaction span. This lets an embedding process pass its active W3C trace context into the subprocess so Claude Code’s spans appear as children of the caller’s distributed trace. Interactive sessions ignore inbound `TRACEPARENT` to avoid accidentally inheriting ambient values from CI or container environments.

[](#span-hierarchy)

Span hierarchy

Each user prompt starts a `claude_code.interaction` root span. API calls, tool calls, and hook executions are recorded as its children. Tool spans have two child spans of their own: one for the time spent waiting on a permission decision and one for the execution itself. When the Task tool spawns a subagent, the subagent’s API and tool spans nest under the parent’s `claude_code.tool` span.

```python
claude_code.interaction
├── claude_code.llm_request
├── claude_code.hook (requires detailed beta tracing)
└── claude_code.tool
├── claude_code.tool.blocked_on_user
├── claude_code.tool.execution
└── (Task tool) subagent claude_code.llm_request / claude_code.tool spans
```

In Agent SDK and `claude -p` sessions, `claude_code.interaction` itself becomes a child of the caller’s span when `TRACEPARENT` is set in the environment.

[](#span-attributes)

Span attributes

Every span carries the [standard attributes](#standard-attributes) plus a `span.type` attribute matching its name. The tables below list the additional attributes set on each span. The `llm_request`, `tool.execution`, and `hook` spans set OpenTelemetry status `ERROR` when they record a failure; the other spans always end with status `UNSET`. **`claude_code.interaction`**

| Attribute | Description | Gated by |
|----|----|----|
| `user_prompt` | Prompt text. Value is `<REDACTED>` unless the gate is set | `OTEL_LOG_USER_PROMPTS` |
| `user_prompt_length` | Prompt length in characters | |
| `interaction.sequence` | 1-based counter of interactions in this session | |
| `interaction.duration_ms` | Wall-clock duration of the turn | |

**`claude_code.llm_request`**

| Attribute | Description | Gated by |
|----|----|----|
| `model` | Model identifier | |
| `gen_ai.system` | Always `anthropic`. OpenTelemetry GenAI semantic convention | |
| `gen_ai.request.model` | Same value as `model`. OpenTelemetry GenAI semantic convention | |
| `query_source` | Subsystem that issued the request, such as `repl_main_thread` or a subagent name | |
| `speed` | `fast` or `normal` | |
| `llm_request.context` | `interaction`, `tool`, or `standalone` depending on the parent span | |
| `duration_ms` | Wall-clock duration including retries | |
| `ttft_ms` | Time to first token in milliseconds | |
| `input_tokens` | Input token count from the API usage block | |
| `output_tokens` | Output token count | |
| `cache_read_tokens` | Tokens read from prompt cache | |
| `cache_creation_tokens` | Tokens written to prompt cache | |
| `request_id` | Anthropic API request ID from the `request-id` response header | |
| `gen_ai.response.id` | Same value as `request_id`. OpenTelemetry GenAI semantic convention | |
| `client_request_id` | Client-generated `x-client-request-id` of the final attempt | |
| `attempt` | Total attempts made for this request | |
| `success` | `true` or `false` | |
| `status_code` | HTTP status code when the request failed | |
| `error` | Error message when the request failed | |
| `response.has_tool_call` | `true` when the response contained tool-use blocks | |

Each retry attempt is also recorded as a `gen_ai.request.attempt` span event with `attempt` and `client_request_id` attributes. **`claude_code.tool`**

| Attribute | Description | Gated by |
|----|----|----|
| `tool_name` | Tool name | |
| `duration_ms` | Wall-clock duration including permission wait and execution | |
| `result_tokens` | Approximate token size of the tool result | |
| `file_path` | Target file path for Read, Edit, and Write tools | `OTEL_LOG_TOOL_DETAILS` |
| `full_command` | Command string for the Bash tool | `OTEL_LOG_TOOL_DETAILS` |
| `skill_name` | Skill name for the Skill tool | `OTEL_LOG_TOOL_DETAILS` |
| `subagent_type` | Subagent type for the Task tool | `OTEL_LOG_TOOL_DETAILS` |

When `OTEL_LOG_TOOL_CONTENT=1`, this span also records a `tool.output` span event whose attributes contain the tool’s input and output bodies, truncated at 60 KB per attribute. **`claude_code.tool.blocked_on_user`**

| Attribute | Description | Gated by |
|---------------|-----------------------------------------------------|----------|
| `duration_ms` | Time spent waiting for the permission decision | |
| `decision` | `accept` or `reject` | |
| `source` | Decision source, matching the `tool_decision` event | |

**`claude_code.tool.execution`**

| Attribute | Description | Gated by |
|----|----|----|
| `duration_ms` | Time spent running the tool body | |
| `success` | `true` or `false` | |
| `error` | Error category string when execution failed, such as `Error:ENOENT` or `ShellError`. Contains the full error message instead when the gate is set | `OTEL_LOG_TOOL_DETAILS` |

**`claude_code.hook`** This span is emitted only when detailed beta tracing is active, which requires `ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT` in addition to the trace exporter configuration above. In interactive CLI sessions, this also requires your organization to be allowlisted for the feature. Agent SDK and non-interactive `-p` sessions are not gated. It is not emitted when only `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` is set.

| Attribute | Description | Gated by |
|----|----|----|
| `hook_event` | Hook event type, such as `PreToolUse` | |
| `hook_name` | Full hook name, such as `PreToolUse:Write` | |
| `num_hooks` | Number of matching hook commands executed | |
| `hook_definitions` | JSON-serialized hook configuration | `OTEL_LOG_TOOL_DETAILS` |
| `duration_ms` | Wall-clock duration of all matching hooks | |
| `num_success` | Count of hooks that completed successfully | |
| `num_blocking` | Count of hooks that returned a blocking decision | |
| `num_non_blocking_error` | Count of hooks that failed without blocking | |
| `num_cancelled` | Count of hooks cancelled before completion | |

Additional content-bearing attributes such as `new_context`, `system_prompt_preview`, `tool_input`, and `response.model_output` are emitted only when detailed beta tracing is active. They are not part of the stable span schema.

[](#dynamic-headers)

Dynamic headers

For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically:

[](#settings-configuration)

Settings configuration

Add to your `.claude/settings.json`:

```python
{
"otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh"
}
```

[](#script-requirements)

Script requirements

The script must output valid JSON with string key-value pairs representing HTTP headers:

```python
#!/bin/bash
# Example: Multiple headers
echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"
```

[](#refresh-behavior)

Refresh behavior

The headers helper script runs at startup and periodically thereafter to support token refresh. By default, the script runs every 29 minutes. Customize the interval with the `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` environment variable.

[](#multi-team-organization-support)

Multi-team organization support

Organizations with multiple teams or departments can add custom attributes to distinguish between different groups using the `OTEL_RESOURCE_ATTRIBUTES` environment variable:

```python
# Add custom attributes for team identification
export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"
```

These custom attributes will be included in all metrics and events, allowing you to:

- Filter metrics by team or department
- Track costs per cost center
- Create team-specific dashboards
- Set up alerts for specific teams

**Important formatting requirements for OTEL_RESOURCE_ATTRIBUTES:**The `OTEL_RESOURCE_ATTRIBUTES` environment variable uses comma-separated key=value pairs with strict formatting requirements:

- **No spaces allowed**: Values cannot contain spaces. For example, `user.organizationName=My Company` is invalid
- **Format**: Must be comma-separated key=value pairs: `key1=value1,key2=value2`
- **Allowed characters**: Only US-ASCII characters excluding control characters, whitespace, double quotes, commas, semicolons, and backslashes
- **Special characters**: Characters outside the allowed range must be percent-encoded

**Examples:**

```python
# ❌ Invalid - contains spaces
export OTEL_RESOURCE_ATTRIBUTES="org.name=John's Organization"

# ✅ Valid - use underscores or camelCase instead
export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"

# ✅ Valid - percent-encode special characters if needed
export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
```

Note: wrapping values in quotes doesn’t escape spaces. For example, `org.name="My Company"` results in the literal value `"My Company"` (with quotes included), not `My Company`.

[](#example-configurations)

Example configurations

Set these environment variables before running `claude`. Each block shows a complete configuration for a different exporter or deployment scenario:

```python
# Console debugging (1-second intervals)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=1000

# OTLP/gRPC
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Prometheus
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=prometheus

# Multiple exporters
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console,otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

# Different endpoints/backends for metrics and logs
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

# Metrics only (no events/logs)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

# Events/logs only (no metrics)
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
```

[](#available-metrics-and-events)

Available metrics and events

[](#standard-attributes)

Standard attributes

All metrics and events share these standard attributes:

| Attribute | Description | Controlled By |
|----|----|----|
| `session.id` | Unique session identifier | `OTEL_METRICS_INCLUDE_SESSION_ID` (default: true) |
| `app.version` | Current Claude Code version | `OTEL_METRICS_INCLUDE_VERSION` (default: false) |
| `organization.id` | Organization UUID (when authenticated) | Always included when available |
| `user.account_uuid` | Account UUID (when authenticated) | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (default: true) |
| `user.account_id` | Account ID in tagged format matching Anthropic admin APIs (when authenticated), such as `user_01BWBeN28...` | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` (default: true) |
| `user.id` | Anonymous device/installation identifier, generated per Claude Code installation | Always included |
| `user.email` | User email address (when authenticated via OAuth) | Always included when available |
| `terminal.type` | Terminal type, such as `iTerm.app`, `vscode`, `cursor`, or `tmux` | Always included when detected |

Events additionally include the following attributes. These are never attached to metrics because they would cause unbounded cardinality:

- `prompt.id`: UUID correlating a user prompt with all subsequent events until the next prompt. See [Event correlation attributes](#event-correlation-attributes).
- `workspace.host_paths`: host workspace directories selected in the desktop app, as a string array

[](#metrics)

Metrics

Claude Code exports the following metrics:

| Metric Name | Description | Unit |
|----|----|----|
| `claude_code.session.count` | Count of CLI sessions started | count |
| `claude_code.lines_of_code.count` | Count of lines of code modified | count |
| `claude_code.pull_request.count` | Number of pull requests created | count |
| `claude_code.commit.count` | Number of git commits created | count |
| `claude_code.cost.usage` | Cost of the Claude Code session | USD |
| `claude_code.token.usage` | Number of tokens used | tokens |
| `claude_code.code_edit_tool.decision` | Count of code editing tool permission decisions | count |
| `claude_code.active_time.total` | Total active time in seconds | s |

[](#metric-details)

Metric details

Each metric includes the standard attributes listed above. Metrics with additional context-specific attributes are noted below.

[](#session-counter)

Session counter

Incremented at the start of each session. **Attributes**:

- All [standard attributes](#standard-attributes)
- `start_type`: How the session was started. One of `"fresh"`, `"resume"`, or `"continue"`

[](#lines-of-code-counter)

Lines of code counter

Incremented when code is added or removed. **Attributes**:

- All [standard attributes](#standard-attributes)
- `type`: (`"added"`, `"removed"`)

[](#pull-request-counter)

Pull request counter

Incremented when creating pull requests via Claude Code. **Attributes**:

- All [standard attributes](#standard-attributes)

[](#commit-counter)

Commit counter

Incremented when creating git commits via Claude Code. **Attributes**:

- All [standard attributes](#standard-attributes)

[](#cost-counter)

Cost counter

Incremented after each API request. **Attributes**:

- All [standard attributes](#standard-attributes)
- `model`: Model identifier (for example, “claude-sonnet-4-6”)
- `query_source`: Category of the subsystem that issued the request. One of `"main"`, `"subagent"`, or `"auxiliary"`
- `speed`: `"fast"` when the request used fast mode. Absent otherwise
- `effort`: [Effort level](/docs/en/model-config#adjust-effort-level) applied to the request: `"low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"`. Absent when the model does not support effort.

[](#token-counter)

Token counter

Incremented after each API request. **Attributes**:

- All [standard attributes](#standard-attributes)
- `type`: (`"input"`, `"output"`, `"cacheRead"`, `"cacheCreation"`)
- `model`: Model identifier (for example, “claude-sonnet-4-6”)
- `query_source`: Category of the subsystem that issued the request. One of `"main"`, `"subagent"`, or `"auxiliary"`
- `speed`: `"fast"` when the request used fast mode. Absent otherwise
- `effort`: [Effort level](/docs/en/model-config#adjust-effort-level) applied to the request. See [Cost counter](#cost-counter) for details.

[](#code-edit-tool-decision-counter)

Code edit tool decision counter

Incremented when user accepts or rejects Edit, Write, or NotebookEdit tool usage. **Attributes**:

- All [standard attributes](#standard-attributes)
- `tool_name`: Tool name (`"Edit"`, `"Write"`, `"NotebookEdit"`)
- `decision`: User decision (`"accept"`, `"reject"`)
- `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`
- `language`: Programming language of the edited file, such as `"TypeScript"`, `"Python"`, `"JavaScript"`, or `"Markdown"`. Returns `"unknown"` for unrecognized file extensions.

[](#active-time-counter)

Active time counter

Tracks actual time spent actively using Claude Code, excluding idle time. This metric is incremented during user interactions (typing, reading responses) and during CLI processing (tool execution, AI response generation). **Attributes**:

- All [standard attributes](#standard-attributes)
- `type`: `"user"` for keyboard interactions, `"cli"` for tool execution and AI responses

[](#events)

Events

Claude Code exports the following events via OpenTelemetry logs/events (when `OTEL_LOGS_EXPORTER` is configured):

[](#event-correlation-attributes)

Event correlation attributes

When a user submits a prompt, Claude Code may make multiple API calls and run several tools. The `prompt.id` attribute lets you tie all of those events back to the single prompt that triggered them.

| Attribute | Description |
|----|----|
| `prompt.id` | UUID v4 identifier linking all events produced while processing a single user prompt |

To trace all activity triggered by a single prompt, filter your events by a specific `prompt.id` value. This returns the user_prompt event, any api_request events, and any tool_result events that occurred while processing that prompt.

`prompt.id` is intentionally excluded from metrics because each prompt generates a unique ID, which would create an ever-growing number of time series. Use it for event-level analysis and audit trails only.

[](#user-prompt-event)

User prompt event

Logged when a user submits a prompt. **Event Name**: `claude_code.user_prompt` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"user_prompt"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `prompt_length`: Length of the prompt
- `prompt`: Prompt content (redacted by default, enable with `OTEL_LOG_USER_PROMPTS=1`)
- `command_name`: Command name when the prompt invokes one. Built-in and bundled command names such as `compact` or `debug` are emitted as-is; aliases such as `reset` emit as typed rather than the canonical name. Custom, plugin, and MCP command names collapse to `custom` or `mcp` unless `OTEL_LOG_TOOL_DETAILS=1` is set
- `command_source`: Origin of the command when present: `builtin`, `custom`, or `mcp`. Plugin-provided commands report as `custom`

[](#tool-result-event)

Tool result event

Logged when a tool completes execution. **Event Name**: `claude_code.tool_result` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"tool_result"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `tool_name`: Name of the tool
- `tool_use_id`: Unique identifier for this tool invocation. Matches the `tool_use_id` passed to hooks, allowing correlation between OTel events and hook-captured data.
- `success`: `"true"` or `"false"`
- `duration_ms`: Execution time in milliseconds
- `error_type`: Error category string when the tool failed, such as `"Error:ENOENT"` or `"ShellError"`
- `error` (when `OTEL_LOG_TOOL_DETAILS=1`): Full error message when the tool failed
- `decision_type`: Either `"accept"` or `"reject"`
- `decision_source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`
- `tool_input_size_bytes`: Size of the JSON-serialized tool input in bytes
- `tool_result_size_bytes`: Size of the tool result in bytes
- `mcp_server_scope`: MCP server scope identifier (for MCP tools)
- `tool_parameters` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON string containing tool-specific parameters:
- For Bash tool: includes `bash_command`, `full_command`, `timeout`, `description`, `dangerouslyDisableSandbox`, and `git_commit_id` (the commit SHA, when a `git commit` command succeeds)
- For MCP tools: includes `mcp_server_name`, `mcp_tool_name`
- For Skill tool: includes `skill_name`
- For Task tool: includes `subagent_type`
- `tool_input` (when `OTEL_LOG_TOOL_DETAILS=1`): JSON-serialized tool arguments. Individual values over 512 characters are truncated, and the full payload is bounded to ~4 K characters. Applies to all tools including MCP tools.

[](#api-request-event)

API request event

Logged for each API request to Claude. **Event Name**: `claude_code.api_request` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"api_request"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `model`: Model used (for example, “claude-sonnet-4-6”)
- `cost_usd`: Estimated cost in USD
- `duration_ms`: Request duration in milliseconds
- `input_tokens`: Number of input tokens
- `output_tokens`: Number of output tokens
- `cache_read_tokens`: Number of tokens read from cache
- `cache_creation_tokens`: Number of tokens used for cache creation
- `request_id`: Anthropic API request ID from the response’s `request-id` header, such as `"req_011..."`. Present only when the API returns one.
- `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active
- `query_source`: Subsystem that issued the request, such as `"repl_main_thread"`, `"compact"`, or a subagent name
- `effort`: [Effort level](/docs/en/model-config#adjust-effort-level) applied to the request: `"low"`, `"medium"`, `"high"`, `"xhigh"`, or `"max"`. Absent when the model does not support effort.

[](#api-error-event)

API error event

Logged when an API request to Claude fails. **Event Name**: `claude_code.api_error` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"api_error"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `model`: Model used (for example, “claude-sonnet-4-6”)
- `error`: Error message
- `status_code`: HTTP status code as a string, or `"undefined"` for non-HTTP errors
- `duration_ms`: Request duration in milliseconds
- `attempt`: Total number of attempts made, including the initial request (`1` means no retries occurred)
- `request_id`: Anthropic API request ID from the response’s `request-id` header, such as `"req_011..."`. Present only when the API returns one.
- `speed`: `"fast"` or `"normal"`, indicating whether fast mode was active
- `query_source`: Subsystem that issued the request, such as `"repl_main_thread"`, `"compact"`, or a subagent name
- `effort`: [Effort level](/docs/en/model-config#adjust-effort-level) applied to the request. Absent when the model does not support effort.

[](#api-request-body-event)

API request body event

Logged for each API request attempt when `OTEL_LOG_RAW_API_BODIES` is set. One event is emitted per attempt, so retries with adjusted parameters each produce their own event. **Event Name**: `claude_code.api_request_body` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"api_request_body"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `body`: JSON-serialized Messages API request parameters (system prompt, messages, tools, etc.), truncated at 60 KB. Extended-thinking content in prior assistant turns is redacted. Emitted only in inline mode (`OTEL_LOG_RAW_API_BODIES=1`).
- `body_ref`: Absolute path to a `<dir>/<uuid>.request.json` file containing the untruncated body. Emitted only in file mode (`OTEL_LOG_RAW_API_BODIES=file:<dir>`).
- `body_length`: Untruncated body length. UTF-8 bytes when `OTEL_LOG_RAW_API_BODIES=file:<dir>`, or UTF-16 code units when `=1`
- `body_truncated`: `"true"` when inline truncation occurred. Absent in file mode and when no truncation occurred.
- `model`: Model identifier from the request parameters
- `query_source`: Subsystem that issued the request (for example, `"compact"`)

[](#api-response-body-event)

API response body event

Logged for each successful API response when `OTEL_LOG_RAW_API_BODIES` is set. **Event Name**: `claude_code.api_response_body` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"api_response_body"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `body`: JSON-serialized Messages API response (id, content blocks, usage, stop reason), truncated at 60 KB. Extended-thinking content is redacted. Emitted only in inline mode (`OTEL_LOG_RAW_API_BODIES=1`).
- `body_ref`: Absolute path to a `<dir>/<request_id>.response.json` file containing the untruncated body. Emitted only in file mode (`OTEL_LOG_RAW_API_BODIES=file:<dir>`).
- `body_length`: Untruncated body length. UTF-8 bytes when `OTEL_LOG_RAW_API_BODIES=file:<dir>`, or UTF-16 code units when `=1`
- `body_truncated`: `"true"` when inline truncation occurred. Absent in file mode and when no truncation occurred.
- `model`: Model identifier
- `query_source`: Subsystem that issued the request
- `request_id`: Anthropic API request ID from the response’s `request-id` header, such as `"req_011..."`. Present only when the API returns one.

[](#tool-decision-event)

Tool decision event

Logged when a tool permission decision is made (accept/reject). **Event Name**: `claude_code.tool_decision` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"tool_decision"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `tool_name`: Name of the tool (for example, “Read”, “Edit”, “Write”, “NotebookEdit”)
- `tool_use_id`: Unique identifier for this tool invocation. Matches the `tool_use_id` passed to hooks, allowing correlation between OTel events and hook-captured data.
- `decision`: Either `"accept"` or `"reject"`
- `source`: Decision source - `"config"`, `"hook"`, `"user_permanent"`, `"user_temporary"`, `"user_abort"`, or `"user_reject"`

[](#permission-mode-changed-event)

Permission mode changed event

Logged when the permission mode changes, for example from `Shift+Tab` cycling, exiting plan mode, or an auto mode gate check. **Event Name**: `claude_code.permission_mode_changed` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"permission_mode_changed"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `from_mode`: The previous permission mode, for example `"default"`, `"plan"`, `"acceptEdits"`, `"auto"`, or `"bypassPermissions"`
- `to_mode`: The new permission mode
- `trigger`: What caused the change. One of `"shift_tab"`, `"exit_plan_mode"`, `"auto_gate_denied"`, or `"auto_opt_in"`. Absent when the transition originates from the SDK or bridge

[](#auth-event)

Auth event

Logged when `/login` or `/logout` completes. **Event Name**: `claude_code.auth` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"auth"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `action`: `"login"` or `"logout"`
- `success`: `"true"` or `"false"`
- `auth_method`: Authentication method, such as `"oauth"`
- `error_category`: Categorical error kind when the action failed. The raw error message is never included
- `status_code`: HTTP status code as a string when the action failed with an HTTP error

[](#mcp-server-connection-event)

MCP server connection event

Logged when an MCP server connects, disconnects, or fails to connect. **Event Name**: `claude_code.mcp_server_connection` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"mcp_server_connection"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `status`: `"connected"`, `"failed"`, or `"disconnected"`
- `transport_type`: Server transport, such as `"stdio"`, `"sse"`, or `"http"`
- `server_scope`: Scope the server is configured at, such as `"user"`, `"project"`, or `"local"`
- `duration_ms`: Connection attempt duration in milliseconds
- `error_code`: Error code when the connection failed
- `server_name` (when `OTEL_LOG_TOOL_DETAILS=1`): Configured server name
- `error` (when `OTEL_LOG_TOOL_DETAILS=1`): Full error message when the connection failed

[](#internal-error-event)

Internal error event

Logged when Claude Code catches an unexpected internal error. Only the error class name and an errno-style code are recorded. The error message and stack trace are never included. This event is not emitted when running against Bedrock, Vertex, or Foundry, or when `DISABLE_ERROR_REPORTING` is set. **Event Name**: `claude_code.internal_error` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"internal_error"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `error_name`: Error class name, such as `"TypeError"` or `"SyntaxError"`
- `error_code`: Node.js errno code such as `"ENOENT"` when present on the error

[](#plugin-installed-event)

Plugin installed event

Logged when a plugin finishes installing, from both the `claude plugin install` CLI command and the interactive `/plugin` UI. **Event Name**: `claude_code.plugin_installed` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"plugin_installed"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `marketplace.is_official`: `"true"` if the marketplace is an official Anthropic marketplace, `"false"` otherwise
- `install.trigger`: `"cli"` or `"ui"`
- `plugin.name`: Name of the installed plugin. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`
- `plugin.version`: Plugin version when declared in the marketplace entry. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`
- `marketplace.name`: Marketplace the plugin was installed from. For third-party marketplaces this is included only when `OTEL_LOG_TOOL_DETAILS=1`

[](#skill-activated-event)

Skill activated event

Logged when a skill is invoked. **Event Name**: `claude_code.skill_activated` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"skill_activated"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `skill.name`: Name of the skill. For user-defined and third-party plugin skills the value is the placeholder `"custom_skill"` unless `OTEL_LOG_TOOL_DETAILS=1`
- `skill.source`: Where the skill was loaded from (for example, `"bundled"`, `"userSettings"`, `"projectSettings"`, `"plugin"`)
- `plugin.name` (when `OTEL_LOG_TOOL_DETAILS=1` or the plugin is from an official marketplace): Name of the owning plugin when the skill is provided by a plugin
- `marketplace.name` (when `OTEL_LOG_TOOL_DETAILS=1` or the plugin is from an official marketplace): Marketplace the owning plugin was installed from, when the skill is provided by a plugin

[](#api-retries-exhausted-event)

API retries exhausted event

Logged once when an API request fails after more than one attempt. Emitted alongside the final `api_error` event. **Event Name**: `claude_code.api_retries_exhausted` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"api_retries_exhausted"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `model`: Model used
- `error`: Final error message
- `status_code`: HTTP status code as a string
- `total_attempts`: Total number of attempts made
- `total_retry_duration_ms`: Total wall-clock time across all attempts
- `speed`: `"fast"` or `"normal"`

[](#hook-execution-start-event)

Hook execution start event

Logged when one or more hooks begin executing for a hook event. **Event Name**: `claude_code.hook_execution_start` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"hook_execution_start"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `hook_event`: Hook event type, such as `"PreToolUse"` or `"PostToolUse"`
- `hook_name`: Full hook name including matcher, such as `"PreToolUse:Write"`
- `num_hooks`: Number of matching hook commands
- `managed_only`: `"true"` when only managed-policy hooks are permitted
- `hook_source`: `"policySettings"` or `"merged"`
- `hook_definitions`: JSON-serialized hook configuration. Included only when both detailed beta tracing and `OTEL_LOG_TOOL_DETAILS=1` are enabled

[](#hook-execution-complete-event)

Hook execution complete event

Logged when all hooks for a hook event have finished. **Event Name**: `claude_code.hook_execution_complete` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"hook_execution_complete"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `hook_event`: Hook event type
- `hook_name`: Full hook name including matcher
- `num_hooks`: Number of matching hook commands
- `num_success`: Count that completed successfully
- `num_blocking`: Count that returned a blocking decision
- `num_non_blocking_error`: Count that failed without blocking
- `num_cancelled`: Count cancelled before completion
- `total_duration_ms`: Wall-clock duration of all matching hooks
- `managed_only`: `"true"` when only managed-policy hooks are permitted
- `hook_source`: `"policySettings"` or `"merged"`
- `hook_definitions`: JSON-serialized hook configuration. Included only when both detailed beta tracing and `OTEL_LOG_TOOL_DETAILS=1` are enabled

[](#compaction-event)

Compaction event

Logged when conversation compaction completes. **Event Name**: `claude_code.compaction` **Attributes**:

- All [standard attributes](#standard-attributes)
- `event.name`: `"compaction"`
- `event.timestamp`: ISO 8601 timestamp
- `event.sequence`: monotonically increasing counter for ordering events within a session
- `trigger`: `"auto"` or `"manual"`
- `success`: `"true"` or `"false"`
- `duration_ms`: Compaction duration
- `pre_tokens`: Approximate token count before compaction
- `post_tokens`: Approximate token count after compaction
- `error`: Error message when compaction failed

[](#interpret-metrics-and-events-data)

Interpret metrics and events data

The exported metrics and events support a range of analyses:

[](#usage-monitoring)

Usage monitoring

| Metric | Analysis Opportunity |
|----|----|
| `claude_code.token.usage` | Break down by `type` (input/output), user, team, or model |
| `claude_code.session.count` | Track adoption and engagement over time |
| `claude_code.lines_of_code.count` | Measure productivity by tracking code additions/removals |
| `claude_code.commit.count` & `claude_code.pull_request.count` | Understand impact on development workflows |

[](#cost-monitoring)

Cost monitoring

The `claude_code.cost.usage` metric helps with:

- Tracking usage trends across teams or individuals
- Identifying high-usage sessions for optimization

Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, AWS Bedrock, or Google Cloud Vertex).

[](#alerting-and-segmentation)

Alerting and segmentation

Common alerts to consider:

- Cost spikes
- Unusual token consumption
- High session volume from specific users

All metrics can be segmented by `user.account_uuid`, `user.account_id`, `organization.id`, `session.id`, `model`, and `app.version`.

[](#detect-retry-exhaustion)

Detect retry exhaustion

Claude Code retries failed API requests internally and emits a single `claude_code.api_error` event only after it gives up, so the event itself is the terminal signal for that request. Intermediate retry attempts are not logged as separate events. The `attempt` attribute on the event records how many attempts were made in total. A value greater than `CLAUDE_CODE_MAX_RETRIES` (default `10`) indicates the request exhausted all retries on a transient error. A lower value indicates a non-retryable error such as a `400` response. To distinguish a session that recovered from one that stalled, group events by `session.id` and check whether a later `api_request` event exists after the error.

[](#event-analysis)

Event analysis

The event data provides detailed insights into Claude Code interactions: **Tool Usage Patterns**: analyze tool result events to identify:

- Most frequently used tools
- Tool success rates
- Average tool execution times
- Error patterns by tool type

**Performance Monitoring**: track API request durations and tool execution times to identify performance bottlenecks.

[](#backend-considerations)

Backend considerations

Your choice of metrics, logs, and traces backends determines the types of analyses you can perform:

[](#for-metrics)

For metrics

- **Time series databases (for example, Prometheus)**: Rate calculations, aggregated metrics
- **Columnar stores (for example, ClickHouse)**: Complex queries, unique user analysis
- **Full-featured observability platforms (for example, Honeycomb, Datadog)**: Advanced querying, visualization, alerting

[](#for-events/logs)

For events/logs

- **Log aggregation systems (for example, Elasticsearch, Loki)**: Full-text search, log analysis
- **Columnar stores (for example, ClickHouse)**: Structured event analysis
- **Full-featured observability platforms (for example, Honeycomb, Datadog)**: Correlation between metrics and events

[](#for-traces)

For traces

Choose a backend that supports distributed trace storage and span correlation:

- **Distributed tracing systems (for example, Jaeger, Zipkin, Grafana Tempo)**: Span visualization, request waterfalls, latency analysis
- **Full-featured observability platforms (for example, Honeycomb, Datadog)**: Trace search and correlation with metrics and logs

For organizations requiring Daily/Weekly/Monthly Active User (DAU/WAU/MAU) metrics, consider backends that support efficient unique value queries.

[](#service-information)

Service information

All metrics and events are exported with the following resource attributes:

- `service.name`: `claude-code`
- `service.version`: Current Claude Code version
- `os.type`: Operating system type (for example, `linux`, `darwin`, `windows`)
- `os.version`: Operating system version string
- `host.arch`: Host architecture (for example, `amd64`, `arm64`)
- `wsl.version`: WSL version number (only present when running on Windows Subsystem for Linux)
- Meter Name: `com.anthropic.claude_code`

[](#roi-measurement-resources)

ROI measurement resources

For a comprehensive guide on measuring return on investment for Claude Code, including telemetry setup, cost analysis, productivity metrics, and automated reporting, see the [Claude Code ROI Measurement Guide](https://github.com/anthropics/claude-code-monitoring-guide). This repository provides ready-to-use Docker Compose configurations, Prometheus and OpenTelemetry setups, and templates for generating productivity reports integrated with tools like Linear.

[](#security-and-privacy)

Security and privacy

- Telemetry is opt-in and requires explicit configuration
- Raw file contents and code snippets are not included in metrics or events. Trace spans are a separate data path: see the `OTEL_LOG_TOOL_CONTENT` bullet below
- When authenticated via OAuth, `user.email` is included in telemetry attributes. If this is a concern for your organization, work with your telemetry backend to filter or redact this field
- User prompt content is not collected by default. Only prompt length is recorded. To include prompt content, set `OTEL_LOG_USER_PROMPTS=1`
- Tool input arguments and parameters are not logged by default. To include them, set `OTEL_LOG_TOOL_DETAILS=1`. When enabled, `tool_result` events include a `tool_parameters` attribute with Bash commands, MCP server and tool names, and skill names, plus a `tool_input` attribute with file paths, URLs, search patterns, and other arguments. `user_prompt` events include the verbatim `command_name` for custom, plugin, and MCP commands. Trace spans include the same `tool_input` attribute and input-derived attributes such as `file_path`. Individual values over 512 characters are truncated and the total is bounded to ~4 K characters, but the arguments may still contain sensitive values. Configure your telemetry backend to filter or redact these attributes as needed
- Tool input and output content is not logged in trace spans by default. To include it, set `OTEL_LOG_TOOL_CONTENT=1`. When enabled, span events include full tool input and output content truncated at 60 KB per span. This can include raw file contents from Read tool results and Bash command output. Configure your telemetry backend to filter or redact these attributes as needed
- Raw Anthropic Messages API request and response bodies are not logged by default. To include them, set `OTEL_LOG_RAW_API_BODIES`. With `=1`, each API call emits `api_request_body` and `api_response_body` log events whose `body` attribute is the JSON-serialized payload, truncated at 60 KB. With `=file:<dir>`, untruncated bodies are written to `.request.json` and `.response.json` files under that directory and the events carry a `body_ref` path instead of the inline body. Ship the directory with a log collector or sidecar rather than through the telemetry stream. In both modes, bodies contain the full conversation history (system prompt, every prior user and assistant turn, tool results), so enabling this implies consent to everything the other `OTEL_LOG_*` content flags would reveal. Claude’s extended-thinking content is always redacted from these bodies regardless of other settings

[](#monitor-claude-code-on-amazon-bedrock)

Monitor Claude Code on Amazon Bedrock

For detailed Claude Code usage monitoring guidance for Amazon Bedrock, see [Claude Code Monitoring Implementation (Bedrock)](https://github.com/aws-solutions-library-samples/guidance-for-claude-code-with-amazon-bedrock/blob/main/assets/docs/MONITORING.md).

---
## network-config.md

> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise network configuration

> Configure Claude Code for enterprise environments with proxy servers, custom Certificate Authorities (CA), and mutual Transport Layer Security (mTLS) authentication.

Claude Code supports various enterprise network and security configurations through environment variables. This includes routing traffic through corporate proxy servers, trusting custom Certificate Authorities (CA), and authenticating with mutual Transport Layer Security (mTLS) certificates for enhanced security.

<Note>
All environment variables shown on this page can also be configured in [`settings.json`](../02-Claude-Code-CLI/claude-code-settings-claude-code-docs-d4420b4b52.md).
</Note>

## Proxy configuration

### Environment variables

Claude Code respects standard proxy environment variables:

```bash theme={null}
# HTTPS proxy (recommended)
export HTTPS_PROXY=https://proxy.example.com:8080

# HTTP proxy (if HTTPS not available)
export HTTP_PROXY=http://proxy.example.com:8080

# Bypass proxy for specific requests - space-separated format
export NO_PROXY="localhost 192.168.1.1 example.com .example.com"
# Bypass proxy for specific requests - comma-separated format
export NO_PROXY="localhost,192.168.1.1,example.com,.example.com"
# Bypass proxy for all requests
export NO_PROXY="*"
```

<Note>
Claude Code does not support SOCKS proxies.
</Note>

### Basic authentication

If your proxy requires basic authentication, include credentials in the proxy URL:

```bash theme={null}
export HTTPS_PROXY=http://username:password@proxy.example.com:8080
```

<Warning>
Avoid hardcoding passwords in scripts. Use environment variables or secure credential storage instead.
</Warning>

<Tip>
For proxies requiring advanced authentication (NTLM, Kerberos, etc.), consider using an LLM Gateway service that supports your authentication method.
</Tip>

## Custom CA certificates

If your enterprise environment uses custom CAs for HTTPS connections (whether through a proxy or direct API access), configure Claude Code to trust them:

```bash theme={null}
export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
```

## mTLS authentication

For enterprise environments requiring client certificate authentication:

```bash theme={null}
# Client certificate for authentication
export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem

# Client private key
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem

# Optional: Passphrase for encrypted private key
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"
```

## Network access requirements

Claude Code requires access to the following URLs:

* `api.anthropic.com` - Claude API endpoints
* `claude.ai` - WebFetch safeguards
* `statsig.anthropic.com` - Telemetry and metrics
* `sentry.io` - Error reporting

Ensure these URLs are allowlisted in your proxy configuration and firewall rules. This is especially important when using Claude Code in containerized or restricted network environments.

## Additional resources

* [Claude Code settings](../02-Claude-Code-CLI/claude-code-settings-claude-code-docs-d4420b4b52.md)
* [Environment variables reference](/en/settings#environment-variables)
* [Troubleshooting guide](../21-Account-Support/troubleshooting-claude-code-docs-3f3657ed0f.md)

---
## organization-discovery.md

4. Find and join a Team or Enterprise organization

# Find and join a Team or Enterprise organization

------------------------------------------------------------------------

## Admin setup

### Enable discoverability

Admins and above can manage organization discovery from **[Organization settings \> Identity and access](https://claude.ai/admin-settings/identity)**.

- **New organizations:**

- **Team plans:** Discoverability is on by default. Admins see the option during plan onboarding with it pre-selected.

- **Enterprise plans:** Discoverability is off by default. Admins will see the option disabled on the Identity and access page.

- **Existing organizations:** Discoverability is off by default. Admins can turn it on from settings at any time.

To enable discoverability:

1. Log in as an Admin, Owner, Primary Owner.

2. Navigate to **[Organization settings \> Identity and access](https://claude.ai/admin-settings/identity)**.

3. Your organization’s domains are listed at the top of the page.

4. Find the domain you want users to search for and click the toggle under **Discoverable**.

5. Find **New member approval** under **Global access settings** and choose either “Approve automatically” or “Require admin approval.”

### Configure allowed domains

### Choose an approval mode

Admins select how join requests are handled:

------------------------------------------------------------------------

## How to find and join an organization

- If the organization uses **instant approval**, they're added right away.

If multiple organizations share the same email domain and are all discoverable, users will see all of them and can choose which one to join.

------------------------------------------------------------------------

## Other ways to join an organization

In addition to organization discovery, there are a few other ways to join a Team or Enterprise organization:

- **Note:** If the invite link has been disabled or regenerated by your admin, it will no longer work. Ask your admin to share a new link.

- **Email invitation:** An admin or existing member of the organization may send you an email invitation to join.

- **Admin invitation:** An admin can add you directly from admin settings. See **[Manage members on Team and Enterprise plans](../17-Billing-Plans/managing-members-on-team-and-enterprise-plans.md)**.

------------------------------------------------------------------------

## SSO and organization discovery

If you'd like to enable organization discovery, SSO must be turned off first.

---
## responsible-use-of-anthropic-s-models-guidelines-for-organizations-serving-minor.md

3. Responsible Use of Anthropic's Models: Guidelines for Organizations Serving Minors

# Responsible Use of Anthropic's Models: Guidelines for Organizations Serving Minors

Updated today

At Anthropic, we recognize the unique vulnerabilities and needs of children in digital spaces. In order to create a safer digital environment and mitigate risks, organizations providing minors with the ability to directly interact with products that incorporate our API(s) should implement the following safeguards:

**1. Additional Technical Measures**

Organizations with products serving minors should implement additional safety features tailored to their unique use cases, as they are best situated to understand the specific ways their end users may interact with products that incorporate Anthropic's services. These safety measures may include, but are not limited to:

- Age verification systems to ensure only intended users can access the product

- Content moderation and filtering to block inappropriate or harmful content

- Monitoring and reporting mechanisms to identify and address potential issues

- Educational resources and guidance for minors on safe and responsible use of the product

In addition to these organization-specific measures, Anthropic may make available technical measures intended to tailor product experiences for certain end users, including minors. For example, we may provide a child-safety system prompt, which organizations serving minors should implement as part of a comprehensive suite of safety measures. It is important to note that, while helpful, these technical measures are not infallible and should be used in conjunction with the organization's own safety features to ensure a robust approach to child safety.

**2. Regulatory Compliance**

It is the responsibility of organizations to comply with all applicable child safety and data privacy regulations, such as the Children's Online Privacy Protection Act (COPPA) in the United States. Compliance with these regulations should be clearly stated on the organization’s website or similar public-facing documentation.

**3. Disclosure Requirements**

Organizations must disclose to their users that they are interacting with an AI system rather than a human.

Anthropic will periodically audit organizations for compliance with these safeguards. If your organization has a high violation rate and has not implemented these safety recommendations, we may ask you to implement them. Failure to implement these recommendations when requested, or a continued high violation rate, may lead to the suspension or termination of your account.

---
## restrict-access-to-claude-with-ip-allowlisting.md

4. Restrict access to Claude with IP allowlisting

# Restrict access to Claude with IP allowlisting

IP allowlisting is available for Enterprise plans only.

IP allowlisting enables Enterprise plan administrators to control which IP addresses can access Claude through their organization. This feature ensures that requests can only be made from approved network locations, providing an additional layer of security.

When enabled, we validate the source IP address of every authenticated request against your organization's configured allowlist. Requests from IP addresses not added to the allowlist will be blocked.

IP allowlisting supports CIDR ranges. For example: `10.0.0.0/8, 2001:db8::/32`.

## How to configure IP allowlisting

If your Enterprise organization is interested in enabling an IP allowlist, please compile a list of all necessary CIDR ranges for your organization, including office locations, VPN exit points, and any other approved access points. Omitting required CIDR ranges could result in users getting locked out of Claude. Then, reach out to your Anthropic Contact or our [Sales team](https://claude.com/contact-sales) to share your list of CIDR ranges. They can add these to your account’s allowlist to enable the feature.

When a request originates from an IP address that’s not in your allowlist, access is denied. Users should contact their IT administrator if they believe they're being blocked in error.

---
## security.md

> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Security

> Learn about Claude Code's security safeguards and best practices for safe usage.

## How we approach security

### Security foundation

Your code's security is paramount. Claude Code is built with security at its core, developed according to Anthropic's comprehensive security program. Learn more and access resources (SOC 2 Type 2 report, ISO 27001 certificate, etc.) at [Anthropic Trust Center](https://trust.anthropic.com).

### Permission-based architecture

Claude Code uses strict read-only permissions by default. When additional actions are needed (editing files, running tests, executing commands), Claude Code requests explicit permission. Users control whether to approve actions once or allow them automatically.

We designed Claude Code to be transparent and secure. For example, we require approval for bash commands before executing them, giving you direct control. This approach enables users and organizations to configure permissions directly.

For detailed permission configuration, see [Identity and Access Management](/en/iam).

### Built-in protections

To mitigate risks in agentic systems:

* **Sandboxed bash tool**: [Sandbox](../22-Safety-Policy/sandboxing-claude-code-docs-5f97cd27c4.md) bash commands with filesystem and network isolation, reducing permission prompts while maintaining security. Enable with `/sandbox` to define boundaries where Claude Code can work autonomously
* **Write access restriction**: Claude Code can only write to the folder where it was started and its subfolders—it cannot modify files in parent directories without explicit permission. While Claude Code can read files outside the working directory (useful for accessing system libraries and dependencies), write operations are strictly confined to the project scope, creating a clear security boundary
* **Prompt fatigue mitigation**: Support for allowlisting frequently used safe commands per-user, per-codebase, or per-organization
* **Accept Edits mode**: Batch accept multiple edits while maintaining permission prompts for commands with side effects

### User responsibility

Claude Code only has the permissions you grant it. You're responsible for reviewing proposed code and commands for safety before approval.

## Protect against prompt injection

Prompt injection is a technique where an attacker attempts to override or manipulate an AI assistant's instructions by inserting malicious text. Claude Code includes several safeguards against these attacks:

### Core protections

* **Permission system**: Sensitive operations require explicit approval
* **Context-aware analysis**: Detects potentially harmful instructions by analyzing the full request
* **Input sanitization**: Prevents command injection by processing user inputs
* **Command blocklist**: Blocks risky commands that fetch arbitrary content from the web like `curl` and `wget` by default. When explicitly allowed, be aware of [permission pattern limitations](/en/iam#tool-specific-permission-rules)

### Privacy safeguards

We have implemented several safeguards to protect your data, including:

* Limited retention periods for sensitive information (see the [Privacy Center](https://privacy.anthropic.com/en/articles/10023548-how-long-do-you-store-my-data) to learn more)
* Restricted access to user session data
* User control over data training preferences. Consumer users can change their [privacy settings](https://claude.ai/settings/privacy) at any time.

For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) (for Team, Enterprise, and API users) or [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) (for Free, Pro, and Max users) and [Privacy Policy](https://www.anthropic.com/legal/privacy).

### Additional safeguards

* **Network request approval**: Tools that make network requests require user approval by default
* **Isolated context windows**: Web fetch uses a separate context window to avoid injecting potentially malicious prompts
* **Trust verification**: First-time codebase runs and new MCP servers require trust verification
* Note: Trust verification is disabled when running non-interactively with the `-p` flag
* **Command injection detection**: Suspicious bash commands require manual approval even if previously allowlisted
* **Fail-closed matching**: Unmatched commands default to requiring manual approval
* **Natural language descriptions**: Complex bash commands include explanations for user understanding
* **Secure credential storage**: API keys and tokens are encrypted. See [Credential Management](/en/iam#credential-management)

<Warning>
**Windows WebDAV security risk**: When running Claude Code on Windows, we recommend against enabling WebDAV or allowing Claude Code to access paths such as `\\*` that may contain WebDAV subdirectories. [WebDAV has been deprecated by Microsoft](https://learn.microsoft.com/en-us/windows/whats-new/deprecated-features#:~:text=The%20Webclient%20$WebDAV$%20service%20is%20deprecated) due to security risks. Enabling WebDAV may allow Claude Code to trigger network requests to remote hosts, bypassing the permission system.
</Warning>

**Best practices for working with untrusted content**:

1. Review suggested commands before approval
2. Avoid piping untrusted content directly to Claude
3. Verify proposed changes to critical files
4. Use virtual machines (VMs) to run scripts and make tool calls, especially when interacting with external web services
5. Report suspicious behavior with `/bug`

<Warning>
While these protections significantly reduce risk, no system is completely
immune to all attacks. Always maintain good security practices when working
with any AI tool.
</Warning>

## MCP security

Claude Code allows users to configure Model Context Protocol (MCP) servers. The list of allowed MCP servers is configured in your source code, as part of Claude Code settings engineers check into source control.

We encourage either writing your own MCP servers or using MCP servers from providers that you trust. You are able to configure Claude Code permissions for MCP servers. Anthropic does not manage or audit any MCP servers.

## IDE security

See [VS Code security and privacy](/en/vs-code#security-and-privacy) for more information on running Claude Code in an IDE.

## Cloud execution security

When using [Claude Code on the web](../02-Claude-Code-CLI/claude-code-on-the-web-69d53821d4.md), additional security controls are in place:

* **Isolated virtual machines**: Each cloud session runs in an isolated, Anthropic-managed VM
* **Network access controls**: Network access is limited by default and can be configured to be disabled or allow only specific domains
* **Credential protection**: Authentication is handled through a secure proxy that uses a scoped credential inside the sandbox, which is then translated to your actual GitHub authentication token
* **Branch restrictions**: Git push operations are restricted to the current working branch
* **Audit logging**: All operations in cloud environments are logged for compliance and audit purposes
* **Automatic cleanup**: Cloud environments are automatically terminated after session completion

For more details on cloud execution, see [Claude Code on the web](../02-Claude-Code-CLI/claude-code-on-the-web-69d53821d4.md).

## Security best practices

### Working with sensitive code

* Review all suggested changes before approval
* Use project-specific permission settings for sensitive repositories
* Consider using [devcontainers](../02-Claude-Code-CLI/development-containers-claude-code-docs.md) for additional isolation
* Regularly audit your permission settings with `/permissions`

### Team security

* Use [managed settings](/en/iam#managed-settings) to enforce organizational standards
* Share approved permission configurations through version control
* Train team members on security best practices
* Monitor Claude Code usage through [OpenTelemetry metrics](monitoring-claude-code-docs-72c46f3dc8.md)

### Reporting security issues

If you discover a security vulnerability in Claude Code:

1. Do not disclose it publicly
2. Report it through our [HackerOne program](https://hackerone.com/anthropic-vdp/reports/new?type=team\&report_type=vulnerability)
3. Include detailed reproduction steps
4. Allow time for us to address the issue before public disclosure

## Related resources

* [Sandboxing](../22-Safety-Policy/sandboxing-claude-code-docs-5f97cd27c4.md) - Filesystem and network isolation for bash commands
* [Identity and Access Management](/en/iam) - Configure permissions and access controls
* [Monitoring usage](monitoring-claude-code-docs-72c46f3dc8.md) - Track and audit Claude Code activity
* [Development containers](../02-Claude-Code-CLI/development-containers-claude-code-docs.md) - Secure, isolated environments
* [Anthropic Trust Center](https://trust.anthropic.com) - Security certifications and compliance

---
## set-up-jit-or-scim-provisioning.md

# Set up JIT or SCIM provisioning

JIT provisioning is available for Team plans, Enterprise plans, and Console organizations. SCIM provisioning is available for Enterprise and Console organizations only.

This guide covers how to configure user provisioning and role assignment for your Claude or Claude Console organization.

**Before you begin:** This guide assumes you have already completed the steps in **[Set up single sign-on (SSO)](../21-Account-Support/setting-up-single-sign-on-sso.md)**, including domain verification and SSO configuration with your Identity Provider (IdP), and you have an Admin (Console) or Owner (Claude) role.

------------------------------------------------------------------------

## Step 1: Choose your provisioning mode

Once SSO is configured, you need to decide how users will be provisioned to your organization. This is controlled by the **Provisioning mode** setting in **[Organization](https://claude.ai/admin-settings/organization)** **[settings \> Identity and access](https://claude.ai/admin-settings/identity)**.

### Provisioning options

**Invite only** is the default. Users are added and removed directly in Claude or Console settings.

**Approve automatically (JIT):** Users assigned to your Anthropic IdP app are automatically provisioned when they first log in. This option is available to all plans.

**Sync with SCIM:** Users are automatically provisioned and deprovisioned based on assignments in your IdP, without requiring them to log in first. SCIM is available for Enterprise plans and Console organizations with their own parent organization or joined to an Enterprise parent organization. SCIM is not available for Team plans or Console organizations joined to a Team plan's parent organization.

### Provisioning behavior overview

Use this table to help decide which provisioning mode is right for your organization:

[TABLE]

Both JIT and SCIM can be combined with **Enable group mappings** to control role or seat tier assignment based on IdP group membership. If you select either of these options for your provisioning mode, **Enable group mappings** will appear within that section:

### Available roles and seat tiers

[TABLE]

For information on purchasing seats or adjusting your plan's seat allocation, see our guides for **[Team plans](https://support.claude.com/en/articles/12004354-purchasing-and-managing-seats)** and **[Enterprise plans](../17-Billing-Plans/purchasing-and-managing-seats-on-enterprise-plans.md)**.

------------------------------------------------------------------------

## Step 2: Set up SCIM directory sync (if using SCIM)

**Note:** Skip this step if you're using Invite only or JIT provisioning.

If you chose SCIM as your provisioning mode, you need to establish the connection between your Identity Provider and Anthropic before enabling it.

1. Navigate to your Identity and access settings in Claude (**[claude.ai/admin-settings/identity](http://claude.ai/admin-settings/identity)**) or Console (**[platform.claude.com/settings/identity](http://platform.claude.com/settings/identit)**)

2. In the **Global access settings** section, click “Setup SCIM” (or “Manage SCIM”) next to **Directory sync (SCIM)**.

3. Follow the WorkOS setup guide to configure SCIM in your Identity Provider. You'll need to copy values from WorkOS into your IdP's Anthropic application.

**‼️ When you reach the IdP Group step, pause to review Steps 3 and 4 of this guide, alongside the other guides.**

For IdP-specific JIT / SCIM setup instructions, see:

- **[Okta SAML](https://workos.com/docs/integrations/okta-saml)** / **[OKTA SCIM](https://workos.com/docs/integrations/okta-scim)**

- **[Entra ID SAML](https://workos.com/docs/integrations/entra-id-saml)** / **[Entra ID SCIM](https://workos.com/docs/integrations/entra-id-scim)**

- **[Google SAML](https://workos.com/docs/integrations/google-saml)** / **[Directory Sync](https://workos.com/docs/integrations/google-directory-sync)**

- **[OneLogin SAML](https://workos.com/docs/integrations/onelogin-saml)** / **[OneLogin SCIM](https://workos.com/docs/integrations/onelogin-scim)**

- **[JumpCloud SAML](https://workos.com/docs/integrations/jumpcloud-saml)** / **[JumpCloud SCIM](https://workos.com/docs/integrations/jumpcloud-scim)**

- See additional IdPs **[here](https://workos.com/docs/integrations)**

Once your IdP is connected, continue to Step 3.

------------------------------------------------------------------------

## Step 3: Configure provisioning mode and enable group mappings

1. In the **Global access settings** section of your Identity and access settings, find **Provisioning mode**.

2. Select your chosen option from the dropdown:

1. **Invite only**: New members can only join if manually invited by an existing member. SSO access alone won't add them to your org.

2. **Approve automatically (JIT)**: Allow people with SSO access to join when they first log in. Each new member uses one of your available seats.

3. **Sync with SCIM**: Add or remove members automatically as your directory changes. Your org always stays current.

3. If you selected “Approve automatically (JIT)” or “Sync with SCIM,” do NOT click “Save changes” immediately. You must first ensure all users are assigned to your Anthropic application in your IdP.

4. Once you’ve confirmed all users are assigned in your IdP you can either:

1. Click “Save changes” to complete the set up and trigger the initial provisioning, or

2. Toggle on **Enable group mappings** and move to Step 4.

**Important**: Saving before users are properly assigned will result in those users being deprovisioned from the organization.

------------------------------------------------------------------------

## Step 4: Configure groups in your Identity Provider and map groups to roles and seat types

1. Create groups in your IdP for each role you want to assign. Unless you're on the single-seat Enterprise plan, create groups for each seat type as well.

1. While there are no longer naming requirements for these groups, we recommend including something in the group name (e.g., `anthropic-claude-` or `anthropic-console-`) to make them easier to identify.

2. Add users to the groups you created, ensuring at least one user (including yourself) is in a group that will be mapped to an Admin (Console) or Owner (Claude) role.

3. Return to your Identity and access settings in Claude or Console, and find **Provisioning mode**.

4. Toggle **Enable group mappings** on (if it’s not already):

5. In the **Enable group mappings** section, click “Add” next to each role and select the corresponding group from your IdP in the dropdown.

1. **Note:** When using group mappings, you *must* assign all users to a role-based group in order to ensure they’re provisioned an account. Assigning users to seat-tier based groups is optional.

6. **For all plans except single-seat Enterprise:** In the **Assign seat tiers to IdP groups** section (optional), click "Add" next to each seat type and select the corresponding group from your IdP. If a user isn't assigned to a seat type group, they will be assigned to the highest available type by default.

1. **For single-seat Enterprise:** Seat type mapping does not apply. All provisioned users are automatically assigned an Enterprise seat, provided one is available in your organization.

7. Verify all necessary groups are mapped to the appropriate roles and seat types.

8. Click “Save changes.”

1. **Note:** Microsoft Entra only pushes SCIM changes every 40 minutes, so there may be a delay before changes appear. You can check which users are synced from your IdP by clicking "Manage SCIM" and viewing the Directory. Those users in the Directory will be provisioned to Claude / Console.

**Important:** All users who need access must be assigned to the appropriate groups before you save your group mappings configuration. These users should already be assigned to your Anthropic application in your IdP from when you enabled SSO.

------------------------------------------------------------------------

## Troubleshooting

### Users assigned correctly and showing in the directory but aren’t being added to the Claude as members?

Verify you have enough seats purchased and available to add members to your org.

1. Check the number of available seats shown in **[Organization](https://claude.ai/admin-settings/organization)** **[settings \> Billing](https://claude.ai/admin-settings/billing)** and purchase additional seats if needed (see our guides for **[Team plans](https://support.claude.com/en/articles/12004354-purchasing-and-managing-seats)** and **[Enterprise plans](../17-Billing-Plans/purchasing-and-managing-seats-on-enterprise-plans.md)**).

2. Once you have available seats, go back to the Identity and access page and click “Sync now,” next to **Directory sync (SCIM)**. This will trigger a sync to provision accounts for those users not yet added as members.

### Users aren't being provisioned with the correct role

1. Verify the user is assigned to the correct group in your IdP.

2. Verify the group is mapped to the correct role in your Identity and access settings.

3. **For JIT:** The user needs to log out and log back in for role changes to take effect.

4. **For SCIM:** Click "Sync Now" to prompt an immediate sync, or wait for the automatic sync cycle.

### I lost Admin/Owner access after enabling group mappings

This happens when the person configuring group mappings isn't assigned to a group mapped to an Admin or Owner role, causing their permissions to be downgraded to User.

To fix this:

**Option 1: Have another Admin/Owner reinstate your role**

1. Contact another Admin or Owner of your organization.

2. Ask them to navigate to **[Organization settings \> Organization](https://claude.ai/admin-settings/organization)** (for Claude) or **[Settings \> Members](https://platform.claude.com/settings/members)** (for Console).

3. Have them change your role back to Admin or Owner.

**Option 2: Fix via your Identity Provider**

1. In your IdP, assign yourself to a group with the correct prefix that maps to an Admin or Owner role.

2. **For JIT:** Log out and log back in to regain access.

3. **For SCIM:** Ask another Admin or Owner to click "Sync Now" in the Identity and access settings, or wait for the automatic sync cycle.

---
## setting-up-jit-or-scim-provisioning.md