> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/ai/claude.md).

# Claude

Discover users, track token usage, monitor Claude and Claude Code activity, and manage members' spend limits across your organization via the Anthropic Admin API

Claude is Anthropic's AI assistant, used by organizations for coding, writing, analysis, and automation. Claude Code is Anthropic's agentic coding tool for software engineers. Connecting Claude to Harmony via the Anthropic Admin API gives IT teams visibility into AI tool adoption and spend - tracking who is using Claude and Claude Code and how much token capacity they're consuming.

#### What the Claude integration enables

| Capability             | Description                                                                                                                                   |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| User Discovery         | Surface all Claude users in Harmony's software inventory, including every organization member and accepted invited users                      |
| Token Usage Tracking   | Monitor per-user token consumption across Claude and Claude Code                                                                              |
| Cost Visibility        | See estimated USD spend broken down by user and by individual API key                                                                         |
| Usage Activity         | Track daily per-user usage to identify seats with no recent activity                                                                          |
| Spend Limit Management | Read and change members' monthly spend limits, and approve or deny their requests for more usage, from Custom Agents (Claude Enterprise only) |
| Multi-Instance Support | Connect multiple Anthropic organizations if needed                                                                                            |

#### Prerequisites

* **Console connection**: An **admin** of the Anthropic organization, to create an Admin API key (starting with `sk-ant-admin01-`)
* **Claude Enterprise connection**: The Claude Enterprise organization's **primary owner**, to enable API access and create an Analytics API key (starting with `sk-ant-api01-`)
* **Spend limit management (optional)**: Claude Enterprise with usage credits turned on - the primary owner turns them on in claude.ai billing settings
* **Harmony Account**: Active Harmony workspace

{% hint style="warning" %}
Harmony supports two Anthropic key types, and the key you paste must match the **Key Type** you select:

* **Console (Admin API)** - an Admin API key starting with `sk-ant-admin01-`
* **Enterprise Analytics** - an Analytics API key starting with `sk-ant-api01-`, created in claude.ai and carrying the `read:analytics` scope. The `read:spend_limits` and `write:spend_limits` scopes are optional; add them only to manage spend limits from agents

The two key types are not interchangeable: an Admin API key cannot call the Claude Enterprise Analytics API, and an Analytics API key cannot call the Admin API.
{% endhint %}

#### Connect Claude to Harmony

**Step 1: Generate an API Key**

**Option A - Claude Console (Admin API key)**

1. Go to [Claude Console](https://platform.claude.com) and sign in as an organization **admin**
2. Navigate to **Settings** > **Admin keys**
3. Click **Create admin key**, enter a name (e.g. `Harmony Integration`), and choose a key expiration
4. Click **Add**
5. Copy the key - it starts with `sk-ant-admin01-` and is shown only once

Console Admin keys have no selectable scopes; every key carries full access to the endpoints that accept Admin API keys.

**Option B - Claude Enterprise (Analytics API key)**

1. Go to [claude.ai](https://claude.ai) and sign in as the organization's **primary owner**
2. Navigate to **Organization settings** > **API** and enable public API access
3. In the **Keys** section, click **+ Create key**, name it, and select the `read:analytics` scope. Optionally, to manage spend limits from agents, also select `read:spend_limits` and `write:spend_limits`
4. Copy the key - it starts with `sk-ant-api01-` and is shown only once

**Step 2: Navigate to Integrations**

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Claude** under **AI** (or search for it by name) and click its card

**Step 3: Enter Credentials**

1. If a Claude instance is already connected, click **+ Create instance**
2. Enter an **Instance name** (required)
3. Select the **Key Type** - **Console (Admin API)** or **Enterprise Analytics**
4. Paste your **API key**
5. Click **Connect**

When you click **Connect**, Harmony validates the key format against the selected key type and checks the key with Anthropic. If the key does not match - for example, a standard API key entered as a Console key - the connection is rejected with an error instead of being saved, preventing silent misconfigurations that could cause the integration to fail after setup.

{% hint style="info" %}
For organizations with multiple Anthropic accounts, you can add multiple instances by repeating this process for each account.
{% endhint %}

#### How Claude instances appear in Harmony

If you have both a Console connection and a Claude Enterprise Analytics connection, Harmony distinguishes between them clearly in your inventory:

* Your Console connection is labeled **Claude**
* Your Claude Enterprise Analytics connection is labeled **Claude.ai Enterprise**

Both instances are grouped together under a single Claude application card. No configuration changes are needed - existing connections update automatically.

#### Manage spend limits in agents

On Claude Enterprise, every member has a monthly spend limit, inherited from their seat tier, their group, or the organization unless an admin set one for them personally. Members who reach it can click **Request more usage** in claude.ai. Five Claude steps in the Custom Agent Builder let an agent read and change these limits and work that queue of requests, for example to raise someone's limit after their manager approves it.

| Step                         | What it does                                                                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Get User Spend Limit**     | Reads a member's monthly limit, where it comes from (their own limit, seat tier, group or organization), and how much they have spent so far this month |
| **Set User Spend Limit**     | Sets a member's own monthly limit, replacing any they already have                                                                                      |
| **Remove User Spend Limit**  | Removes a member's own limit, so the seat tier, group or organization limit applies again. Does nothing when they have none                             |
| **List Increase Requests**   | Lists the **Request more usage** requests members raised, with each member's current limit and spend while the request is pending                       |
| **Resolve Increase Request** | Approves a request with a new monthly limit, or denies it. The **Monthly limit** field appears once you choose **Approve**                              |

Pick the member as a Harmony employee (matched by their work email), by email, or by their Claude user ID. Amounts are in your organization's billing currency, in whole units - enter `250` for $250. A limit you set is rounded up to the next cent, never down.

When a step resolves a request, Anthropic does not email the member about the outcome, so the agent can tell them itself. Turn on **Notify member** in the step to have Anthropic email them as well.

The [AI Usage Limits](https://github.com/harmonyso/public-docs/tree/main/ai-agents/agents/ai-usage-limits.md) agent uses these steps to raise a member's limit after approval and answer their **Request more usage** requests.

Spend limit management is optional. Without the spend scopes, the Claude integration syncs users, usage and cost exactly as before; only these five steps need them.

{% hint style="warning" %}
These steps need a **Claude Enterprise** connection (the **Enterprise Analytics** key type) whose key carries the `read:spend_limits` and `write:spend_limits` scopes. A Console connection cannot manage spend limits; the steps stop with an error asking you to reconnect.

Scopes are fixed when a key is created. To add the spend scopes to an **Enterprise Analytics** connection you already have:

1. Create a new key with `read:analytics`, `read:spend_limits` and `write:spend_limits`
2. In Harmony, open the **Claude** card and click the connection
3. Click **Replace** next to **API key**, paste the new key, and click **Save changes**

The new key must belong to the same Claude organization. If your existing connection uses the **Console (Admin API)** key type, add the new key as a new Claude connection with the **Enterprise Analytics** key type instead, pick the new connection in your agents' settings, then delete the old one.
{% endhint %}

#### What Harmony Syncs

**From Anthropic:**

* Users - name, email, and organization role from a Console connection; email only from an Enterprise Analytics connection
* Per-user token consumption (Claude and Claude Code)
* Per-API-key usage and estimated USD cost
* Daily per-user usage activity - Harmony does not sync sign-in or login events
* The Anthropic organization each user belongs to, and the workspace name recorded on each API key

**User visibility**

Harmony pulls in your complete Anthropic user base from two sources:

* **Organization members** - sourced from Anthropic's users endpoint, which returns every member of the organization along with their role
* **Accepted invited users** - sourced from Anthropic's invites endpoint

Pending invites are excluded, as are invited users without an email address. Together, these two sources reflect your full Claude user base in Harmony.

**API key usage and cost breakdown**

Claude API usage and estimated USD cost are tracked per individual API key, giving you granular visibility into how each key consumes your Anthropic budget. Each key is reported with its name and owner (email and display name). Costs are derived from Anthropic's rate table across model, service tier, context window, inference geography, and token type, reconciling to your organization's total spend.

Previously, cost data was only available at the organization level - now you can see exactly which keys are driving usage.

**Estimated cost on instance users table**

The **Estimated Cost** column on the instance users table shows each user's total estimated USD spend, sortable ascending or descending. Hovering over a cost cell shows a tooltip that breaks down spend by Claude model, rounded to two decimal places.

#### Use Cases

<details>

<summary>AI Spend Management</summary>

Track token usage and estimated USD cost per user, per API key, and per team to allocate Claude costs accurately and forecast spend

</details>

<details>

<summary>Spend Limit Increases</summary>

Pick up members' **Request more usage** requests, route them for approval, and raise the limit automatically - or reset temporary increases at the start of each month

</details>

<details>

<summary>Claude Code Adoption</summary>

Measure Claude Code usage across engineering teams to understand developer AI tool adoption

</details>

<details>

<summary>License Reclamation</summary>

Identify inactive Claude users and reclaim seats to optimize subscription costs

</details>

<details>

<summary>Offboarding</summary>

Confirm Claude access has been revoked when employees leave, as part of Harmony offboarding agents

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/ai/claude.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
