> 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/chatgpt.md).

# ChatGPT

Discover your OpenAI organization members, track per-user token consumption via the OpenAI Admin API, and connect a ChatGPT Enterprise workspace

Harmony's ChatGPT integration connects directly to the OpenAI Admin API, giving your IT and finance teams a unified view of your OpenAI organization's members, invites, and token consumption alongside all your other SaaS tools. Harmony pulls real data from the OpenAI API so you are working with actual token consumption figures rather than flat seat estimates - broken down by employee and model.

{% hint style="warning" %}
**The ChatGPT integration has two key types, and they connect to different OpenAI surfaces:**

* **OpenAI Platform** reads your OpenAI API platform organization through the `api.openai.com/v1/organization/*` Admin API endpoints: developer platform members, invites, and API token usage. This is what powers user discovery and token usage tracking.
* **ChatGPT Enterprise** connects one ChatGPT Enterprise workspace through the ChatGPT workspace Admin API at `api.chatgpt.com`, for upcoming features that manage the workspace. An Enterprise connection does not sync members or usage into Harmony's inventory, so ChatGPT Enterprise seats will not appear there.
  {% endhint %}

#### What the ChatGPT integration enables

| Capability             | Description                                                                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User Discovery         | Surface the members of your OpenAI organization in Harmony's software inventory                                                                                                           |
| Seat Inventory         | Track organization members and pending or expired invites as seats, refreshed every 6 hours. Members are recorded as `active`; invites carry their OpenAI status (`pending` or `expired`) |
| Token Usage Tracking   | Monitor per-user, per-model token consumption from OpenAI's Completions usage endpoint, ingested daily                                                                                    |
| Usage Trends           | View each user's token consumption trend in the Activity column as daily usage accumulates                                                                                                |
| Multi-Instance Support | Connect multiple OpenAI organizations or ChatGPT Enterprise workspaces                                                                                                                    |

#### Prerequisites

* **OpenAI Platform connection**: An **owner** of the OpenAI organization, to create an Admin API key (starting with `sk-admin-`)
* **ChatGPT Enterprise connection**: An **Owner** or **Admin** of the ChatGPT Enterprise workspace, to create a workspace Admin key, and the workspace's **Workspace ID**
* **Harmony Account**: Active Harmony workspace

{% hint style="warning" %}
The key you paste must match the **Key Type** you select:

* **OpenAI Platform (Admin API)** - an OpenAI Platform Admin API key starting with `sk-admin-`. Regular project API keys (`sk-proj-...`) and standard API keys (`sk-...`) will not work
* **ChatGPT Enterprise** - a workspace Admin key created in the ChatGPT Admin console for the workspace you connect, plus that workspace's ID. The key needs permission to read workspace users. The `chatgpt.enterprise.usage_limit.read` and `chatgpt.enterprise.usage_limit.write` permissions are optional; they are for upcoming usage limit features and Harmony does not use them yet

The two key types are not interchangeable: an OpenAI Platform Admin key cannot call the ChatGPT workspace Admin API, and a ChatGPT workspace Admin key cannot call the OpenAI Platform Admin API.
{% endhint %}

#### Connect ChatGPT to Harmony

**Step 1: Generate an Admin API Key**

**Option A - OpenAI Platform (Admin API key)**

1. Go to [OpenAI Platform admin keys](https://platform.openai.com/settings/organization/admin-keys) and sign in as an organization owner
2. Click **+ Create new Admin key**
3. Enter a name (e.g. `Harmony Integration`), under **Permissions** select **Read only** (Harmony only reads), and click **Create admin key**
4. Copy the key - it starts with `sk-admin-` and will not be shown again

{% hint style="info" %}
**Create new secret key** on the regular API keys page produces a project key (`sk-proj-...`), which this integration cannot use. Make sure you are on the **Admin keys** page.
{% endhint %}

**Option B - ChatGPT Enterprise (workspace Admin key)**

1. Go to the [ChatGPT Admin console](https://chatgpt.com/admin) and sign in as a workspace **Owner** or **Admin**
2. Navigate to **Credentials** > **Admin keys** and create a key with a descriptive name (e.g. `Harmony Integration`)
3. Select the workspace you want to connect, and choose **Custom permissions**: grant read access to workspace users. Optionally, to prepare for upcoming usage limit features, also grant `chatgpt.enterprise.usage_limit.read` and `chatgpt.enterprise.usage_limit.write`
4. Copy the key and store it securely - it is shown only once
5. Copy the **Workspace ID** from your workspace settings in the ChatGPT Admin console

{% hint style="info" %}
Each workspace Admin key works for one ChatGPT workspace only. To connect several workspaces, create a key in each and add one Harmony instance per workspace.
{% endhint %}

**Step 2: Navigate to Integrations**

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

**Step 3: Enter Credentials**

1. If a ChatGPT instance is already connected, click **+ Create instance**
2. Enter an **Instance name** (required)
3. Select the **Key Type** - **OpenAI Platform (Admin API)** or **ChatGPT Enterprise**
4. Paste your key in **Admin API key**
5. For **ChatGPT Enterprise**, enter the **Workspace ID**. Leave it empty for OpenAI Platform keys
6. Click **Connect**

When you click **Connect**, Harmony checks the key against the selected key type. A ChatGPT Enterprise key is also checked with OpenAI by listing one member of the workspace, so a key from the wrong workspace, a missing permission, or an OpenAI Platform key entered as a ChatGPT Enterprise key is rejected with an error instead of being saved.

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

#### Disconnect ChatGPT from Harmony

1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **ChatGPT** under **AI** and click its card
4. Click the delete (trash) icon next to the instance you want to remove
5. Confirm when prompted

Once disconnected, Harmony stops syncing data from OpenAI. Previously synced data remains available in Harmony. To fully revoke access, delete the Admin API key in the OpenAI Platform, or the workspace Admin key in the ChatGPT Admin console, as well.

#### What Harmony Syncs

**From OpenAI (OpenAI Platform key type):**

* Organization members (name, email, and OpenAI user ID), refreshed every 6 hours
* Member roles - OpenAI's platform roles `owner` and `reader`, shown in Harmony as admin and member
* Pending and expired invites, tracked as seats with their OpenAI status. Accepted invites are skipped because the person already appears in the member list
* Per-user, per-model token counts from OpenAI's Completions usage endpoint, ingested daily
* The OpenAI organization the Admin API key belongs to, used to group data per connected account

{% hint style="info" %}
**Token usage covers Completions only.** Harmony reads OpenAI's Completions usage endpoint. Usage of images, audio, embeddings, moderations, vector stores, web search, and file search is not collected, so totals understate consumption for organizations using those APIs. OpenAI's usage endpoint reports token counts only - it does not report cost.
{% endhint %}

{% hint style="info" %}
**Historical data on first connection:** Harmony backfills the last 7 days of token usage when you first connect, then keeps usage in sync with a daily poll. Longer usage trends build up from the connection date onwards.
{% endhint %}

A ChatGPT Enterprise connection does not sync members or usage. Harmony reads the workspace only when you connect it or save the connection.

#### Permissions Explained

**OpenAI Platform key type**

The Admin API key is used read-only. Harmony calls three OpenAI endpoints:

| Endpoint                                 | Purpose                                                           |
| ---------------------------------------- | ----------------------------------------------------------------- |
| `GET /v1/organization/users`             | List organization members for the seat inventory, with their role |
| `GET /v1/organization/invites`           | List pending and expired invites as seats                         |
| `GET /v1/organization/usage/completions` | Collect per-user, per-model daily token counts                    |

**ChatGPT Enterprise key type**

When you connect, Harmony calls one endpoint of the ChatGPT workspace Admin API (`api.chatgpt.com/v1`) to confirm the key and Workspace ID:

| Endpoint                                      | Purpose                                          |
| --------------------------------------------- | ------------------------------------------------ |
| `GET /manage/workspaces/{workspace_id}/users` | Confirm the key can read the workspace's members |

The `chatgpt.enterprise.usage_limit.read` and `chatgpt.enterprise.usage_limit.write` permissions are not used by Harmony yet. They are reserved for upcoming usage limit features.

#### Use Cases

<details>

<summary>AI Spend Management</summary>

Track token usage per user and model to allocate costs accurately and identify high consumers. Daily per-user token counts give you actual consumption data rather than flat seat estimates, so you can make informed decisions about your AI budget.

</details>

<details>

<summary>License Reclamation</summary>

Identify members with little or no recent token consumption and reclaim access to reduce OpenAI costs. Seat status labels (`active` for members, `pending` and `expired` for invites) make it easy to spot lapsed invitations at a glance.

</details>

<details>

<summary>Offboarding</summary>

Confirm OpenAI organization access has been removed when employees leave, as part of Harmony offboarding workflows.

</details>

<details>

<summary>AI Tool Adoption</summary>

Measure OpenAI API adoption across teams and departments to inform AI rollout decisions. Daily usage metrics show exactly how much each team member is consuming, including which models they are consuming tokens from.

</details>

#### Troubleshooting

<details>

<summary>The API key is rejected when connecting</summary>

**Possible causes:**

* The key is a project key (`sk-proj-...`) or a standard API key (`sk-...`) rather than an Admin API key
* The key does not match the selected **Key Type** - for example, an OpenAI Platform key (`sk-admin-...`) entered as a ChatGPT Enterprise key
* For ChatGPT Enterprise: the key was created for a different workspace than the **Workspace ID**, the Workspace ID is wrong, or the key cannot read workspace users

**Solutions:**

1. For OpenAI Platform, create the key on the **Admin keys** page at `platform.openai.com/settings/organization/admin-keys` using **+ Create new Admin key**, as an owner of the OpenAI organization
2. For ChatGPT Enterprise, create the key in the ChatGPT Admin console under **Credentials** > **Admin keys**, for the workspace whose ID you enter, with read access to workspace users

</details>

<details>

<summary>My ChatGPT Enterprise seats are missing</summary>

**Possible causes:**

* The OpenAI Platform key type enumerates OpenAI API platform organization members and invites, which is a different population from ChatGPT Enterprise workspace seats
* A ChatGPT Enterprise connection does not sync seats

**Solutions:**

1. Expect to see the people who belong to your OpenAI developer platform organization. ChatGPT Enterprise workspace seats are not available in Harmony's inventory through this integration

</details>

<details>

<summary>Usage data is missing or lower than expected</summary>

**Possible causes:**

* Only Completions usage is collected - images, audio, embeddings, moderations, vector stores, web search, and file search usage are not included
* Usage older than 7 days before the connection date is not backfilled
* Consumption that OpenAI cannot attribute to a specific user (for example traffic from an API key with no associated user) is not shown against a person

**Solutions:**

1. Wait for the daily usage poll to run after connecting, then check the Activity column
2. Compare against OpenAI's own usage dashboard, which includes the endpoints Harmony does not collect

</details>

#### Data & Privacy

<details>

<summary>Key privacy principles</summary>

For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).

* With an OpenAI Platform key, Harmony reads OpenAI data in read-only mode and does not modify anything in your OpenAI organization
* With a ChatGPT Enterprise key, Harmony only reads the workspace's members to confirm the key, and does not change anything in your ChatGPT workspace
* Harmony does not read prompts, completions, or conversation content - only membership, invites, and aggregated token counts
* Access can be revoked at any time by disconnecting in Harmony or deleting the key in the OpenAI Platform or the ChatGPT Admin console

</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/chatgpt.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.
