> 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/microsoft-copilot.md).
# Microsoft Copilot
Harmony's Microsoft Copilot integration connects your Microsoft 365 tenant to give you visibility into who holds a Copilot license and who actually uses it. Once connected, Harmony syncs your Copilot-licensed user inventory and daily Copilot interaction activity, then surfaces it across your application, instance, and user views - helping you reclaim unused Copilot seats, track adoption by app, and justify Copilot spend.
#### What the Microsoft Copilot integration enables
| Capability | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| License Optimization | Identify Copilot licenses that are assigned but never used, and reclaim the seats |
| Usage Analytics | Track Copilot prompt volume per user, broken down by the app the prompt came from |
| Per-App Adoption | See Copilot adoption separately for Teams, Word, Excel, PowerPoint, Outlook, and Copilot Chat |
| License Tier Visibility | See which Copilot SKU each user holds (Microsoft 365 Copilot, Copilot for Sales, and other Copilot plans) |
| Activity Monitoring | Daily Copilot interaction history sourced from the Microsoft Purview unified audit log |
***
#### Prerequisites
1. **Microsoft 365 Copilot licenses in your tenant** - Harmony inventories only users who hold a Copilot license. A tenant with no Copilot SKUs syncs an empty inventory.
2. **Microsoft Entra Global Administrator** - admin consent is required, because Harmony uses application (app-only) permissions rather than acting as a signed-in user.
3. **Microsoft Purview audit logging enabled** - Copilot usage is read from the unified audit log. If auditing is off, user inventory still syncs but usage data will be empty.
4. **A Harmony account** with admin privileges.
{% hint style="warning" %}
**Cloud availability:** The Microsoft Graph APIs used by this integration are available in the global Microsoft 365 service only. They are **not** available in US Government (GCC High / DoD) or 21Vianet China cloud deployments.
{% endhint %}
***
#### Connect Microsoft Copilot to Harmony
**Step 1: Navigate to Integrations**
1. Log into your Harmony dashboard
2. Navigate to **Settings** > **Integrations**
3. Find **Microsoft Copilot** under **AI**
**Step 2: Authorize with Microsoft**
1. **Initiate the connection**
1. Click the **Microsoft Copilot** integration card
2. Click **Connect**
A Microsoft sign-in window will open.
2. **Sign in as a Global Administrator**
Sign in with a Microsoft Entra account that holds the Global Administrator role. A non-admin account cannot complete this step, because the permissions Harmony requests require tenant-wide admin consent.
3. **Grant admin consent**
1. Review the permissions Harmony is requesting (see [Permissions Explained](#permissions-explained) below)
2. Check **Consent on behalf of your organization** if prompted
3. Click **Accept**
4. The window closes automatically and you are returned to Harmony
Once authorized, Harmony begins syncing. Your Copilot-licensed user inventory is collected first and refreshes every 6 hours. Copilot interaction activity is collected once per day.
{% hint style="info" %}
**Connecting more than one tenant:** Microsoft Copilot supports multiple connected instances. If your organization has more than one Microsoft 365 tenant, repeat the steps above for each tenant - each appears as its own instance in Harmony.
{% endhint %}
***
#### Disconnect Microsoft Copilot from Harmony
1. Log into your Harmony dashboard
2. Navigate to **Settings** > **Integrations**
3. Find **Microsoft Copilot** under **AI** and click the integration card
4. Click **Disconnect**
5. Confirm the disconnection when prompted
Once disconnected, Harmony stops syncing data from Microsoft Copilot. Previously synced data remains available in Harmony. To fully revoke access on the Microsoft side, remove the Harmony enterprise application from **Microsoft Entra admin center** > **Enterprise applications**.
***
#### What Harmony Syncs from Microsoft Copilot
| Data | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| User profiles | Display name, email address, and account status (enabled or disabled) |
| Copilot license | The Copilot plan each user holds, resolved to a friendly name |
| Organizational details | Department, job title, user type, account creation date, and last password change date |
| Active services | The Microsoft 365 service plans currently enabled for the user |
| Copilot interactions | One record per Copilot prompt, with the app it came from, the event type, access mode, license type, and timestamp |
| Prompt volume | Per-user prompt counts, broken down by the Copilot host app |
{% hint style="info" %}
**Where to find Microsoft Copilot data in Harmony:**
* **Applications** - Microsoft Copilot appears as a discovered application with license and usage details at the application and instance level
* **People** - Each employee's profile shows their Copilot license plan, account status, and Copilot prompt activity
{% endhint %}
{% hint style="info" %}
**Sync cadence and history:**
* **User inventory** refreshes every 6 hours, so newly licensed and newly deprovisioned users appear promptly
* **Copilot interactions** sync once per day and backfill the previous 3 days by default, which absorbs the normal delay before audit records become searchable
{% endhint %}
{% hint style="success" %}
**Harmony does not read your Copilot prompts or responses.** Harmony records that an interaction happened and counts it - the app it came from, when it happened, and the license used. The text of prompts and Copilot's replies is never collected or stored.
{% endhint %}
{% hint style="info" %}
**Not included:** This integration does not collect Microsoft Entra directory roles. Administrator status is not synced through the Microsoft Copilot integration.
{% endhint %}
***
#### Permissions Explained
Harmony requests **application (app-only)** Microsoft Graph permissions, which is why a Global Administrator must grant consent for the whole organization.
**Required permissions**
| Permission | Type | Purpose |
| ------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `User.Read.All` | Application | Read user profiles and their assigned licenses, so Harmony can build the inventory of Copilot-licensed users |
| `Organization.Read.All` | Application | Read the tenant's subscribed SKUs to identify which licenses are Copilot licenses, and read the organization identity used to associate synced data with the correct tenant |
| `AuditLogsQuery.Read.All` | Application | Query the Microsoft Purview unified audit log for Copilot interaction records - the source of all usage and adoption data |
{% hint style="warning" %}
**`AuditLogsQuery.Read.All` cannot be narrowed.** Microsoft publishes service-scoped variants of this permission (for Exchange, SharePoint, OneDrive, Entra, and others), but there is no Copilot-scoped variant. Reading Copilot interaction records requires the tenant-wide audit query permission.
The older `AuditLog.Read.All` permission is **not** a substitute. Where it is granted instead, audit queries return successfully with zero records rather than failing - so usage data silently stays empty.
{% endhint %}
***
#### Use Cases
Copilot License Optimization
Microsoft 365 Copilot is a premium per-seat add-on, and unused seats are pure cost. Harmony shows every user holding a Copilot license alongside their actual prompt activity, so you can identify licensed users who have never used Copilot and reclaim or reassign those seats.
Adoption Tracking by Application
Copilot adoption is rarely uniform. Because Harmony records the host app for every interaction, you can see whether your users have adopted Copilot in Teams but not in Excel, and target enablement where it will actually move the needle.
Rollout and Pilot Measurement
When rolling Copilot out to a pilot group or a new department, compare prompt volume across users and teams over time to decide whether to expand the rollout, and to build the internal case for the next tranche of licenses.
Offboarding and Seat Recovery
Copilot license assignments are synced with account status, so departing employees holding a Copilot seat surface immediately during offboarding rather than continuing to bill.
***
#### Troubleshooting
No users appear after connecting
**Possible causes:**
* The tenant has no Microsoft 365 Copilot licenses assigned
* The Copilot license in use is a newer or less common SKU that Harmony does not yet recognize
* The initial sync has not completed yet
**Solutions:**
1. Wait up to 15 minutes for the initial sync to complete
2. In the **Microsoft 365 admin center**, go to **Billing** > **Your products** and confirm you hold an active Microsoft 365 Copilot subscription with assigned seats
3. If you hold Copilot licenses but no users sync, contact Harmony support with your Copilot SKU name so it can be added
Users sync but usage data is empty
**Possible causes:**
* Microsoft Purview audit logging is not enabled for the tenant
* The `AuditLogsQuery.Read.All` permission was not granted - only the older `AuditLog.Read.All`, which returns zero records without erroring
* No Copilot interactions have occurred yet in the period being collected
* Audit records have not become searchable yet
**Solutions:**
1. Confirm auditing is on in the **Microsoft Purview portal** under **Audit** - if the search interface prompts you to start recording user and admin activity, auditing is off
2. In the **Microsoft Entra admin center**, go to **Enterprise applications**, find the Harmony application, open **Permissions**, and verify `AuditLogsQuery.Read.All` is listed and consented
3. Disconnect and reconnect the integration to re-trigger the admin consent prompt if the permission is missing
4. Allow at least 24 hours after connecting before concluding usage data is missing - Copilot audit records take time to become searchable
Usage data lags behind real activity
**Possible causes:**
* Copilot interactions are collected once per day
* Microsoft's unified audit log does not make records searchable immediately after the activity occurs
**Solutions:**
1. Expect roughly a one-day delay between a Copilot prompt and its appearance in Harmony. Harmony re-checks the previous 3 days on every sync, so late-arriving records are picked up automatically.
The connection fails during Microsoft sign-in
**Possible causes:**
* The account used is not a Global Administrator, so it cannot grant organization-wide consent
* Your tenant restricts user consent to applications and requires an admin consent request workflow
* Your tenant is a US Government or 21Vianet China cloud deployment, where these APIs are unavailable
**Solutions:**
1. Retry the connection with a Microsoft Entra Global Administrator account
2. If your tenant uses an admin consent workflow, submit the consent request and connect again after it is approved
3. Confirm your tenant runs in the global Microsoft 365 cloud
Copilot license plan shows an unfamiliar name
**Possible causes:**
* Harmony displays the license name resolved from your tenant's SKU. Where a friendly name is unavailable, the raw Microsoft SKU identifier is shown instead.
**Solutions:**
1. Cross-check the SKU in the **Microsoft 365 admin center** under **Billing** > **Your products**
2. Report the SKU to Harmony support so the friendly name can be added
***
#### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Harmony accesses Microsoft Copilot data in read-only mode and does not modify anything in your Microsoft 365 tenant
* The content of Copilot prompts and responses is never collected or stored - Harmony records only that an interaction occurred, the app it occurred in, and when
* Harmony reads user profile and license data only for users holding a Copilot license
* Integration can be revoked at any time from Harmony settings, or from the Microsoft Entra admin center under **Enterprise applications**
---
# 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/microsoft-copilot.md?ask=&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.