> 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/saas-applications/box.md).
# Box
Harmony's Box integration connects your Box enterprise to give you full visibility into who holds a Box seat, what role they have, and whether they are actually using it. Once connected, Harmony automatically syncs your Box user directory and enterprise activity log and surfaces the results across your application, instance, and user views - helping you optimize licenses, track adoption, and spot dormant accounts.
#### What the Box integration enables
| Capability | Description |
| ----------------------- | ------------------------------------------------------------------------------------ |
| License Optimization | Identify Box seats that are assigned but unused, and reclaim them |
| Usage Analytics | Measure real content activity per user - uploads, downloads, previews, edits, shares |
| Role Visibility | See each user's Box enterprise role (Admin, Co-Admin, or User) for access reviews |
| Activity Monitoring | Track sign-in events with up to 90 days of history pulled on first connection |
| License Tier Visibility | See whether each account occupies an enterprise seat (Paid, Free, or Unknown) |
***
#### Prerequisites
1. **A Box Business plan or higher** - the enterprise event log that powers activity and usage data is a Box Business Plan feature
2. **Box Administrator access** - the person authorizing the connection must be a Box **enterprise admin or co-admin** with the **Run new reports and access existing reports** permission. Box denies the enterprise event log to anyone else
3. **A Harmony account** with admin privileges
{% hint style="warning" %}
The Box connection inherits the permissions of the person who authorizes it. If a non-admin connects Box, Harmony can authenticate but Box will refuse the user directory and the event log, and no data will sync. Always connect with an admin or co-admin account.
{% endhint %}
***
#### Connect Box to Harmony
**Step 1: Navigate to Integrations**
1. Log into your Harmony dashboard
2. Navigate to **Settings** > **Integrations**
3. Find **Box** under **SaaS Applications**
**Step 2: Authorize Box**
1. **Initiate the connection**
1. Click the **Box** integration card
2. Click **Connect**
A Box authorization window will open.
2. **Authorize in Box**
Sign in with your Box administrator account if prompted.
1. Review the permissions Harmony is requesting (see [Permissions Explained](#permissions-explained) below)
2. Click **Grant access to Box** to authorize the connection
3. The window closes automatically and you are returned to Harmony
There is nothing to copy, paste, or configure - Harmony discovers your Box enterprise automatically from the authorized account.
Once authorized, Harmony begins syncing your Box data. The initial sync may take a few minutes depending on your enterprise size. Up to 90 days of historical sign-in and content activity is pulled in on the first connection. Your user directory then refreshes every 6 hours, and activity is collected every hour.
***
#### Disconnect Box from Harmony
1. Log into your Harmony dashboard
2. Navigate to **Settings** > **Integrations**
3. Find **Box** under **SaaS Applications** and click the integration card
4. Click **Disconnect**
5. Confirm the disconnection when prompted
Once disconnected, Harmony stops syncing data from Box. Previously synced data remains available in Harmony.
***
#### What Harmony Syncs from Box
| Data | Description |
| ------------------ | -------------------------------------------------------------------------------------- |
| User profiles | Name, login email, job title, phone, time zone, and language |
| Roles | The Box enterprise role - Admin, Co-Admin, or User - shown verbatim for access reviews |
| Account status | Active or inactive, including Box's restricted-but-active states |
| License tier | Whether the account occupies an enterprise seat (Paid, Free, or Unknown) |
| Storage | Storage used and storage allocated per user |
| Sign-in activity | Successful Box sign-in events, with up to 90 days of history on first connection |
| Content activity | A daily per-user count of content interactions, with a breakdown by action type |
| Enterprise details | Your Box enterprise name and ID, used to group all Box data under one application |
The content activity signal is built from the Box actions that show someone genuinely working in Box: uploads, downloads, previews, edits, opens, copies, moves, renames, deletes, restores, shares, syncs, email sends, comments, collaboration invites, locks, and unlocks.
{% hint style="info" %}
**Where to find Box data in Harmony:**
* **Applications** - Box appears as a discovered application with license and usage details, including activity metrics at the application and instance level
* **People** - Each employee's profile shows their Box role, license tier, last activity, and per-user content activity
{% endhint %}
{% hint style="info" %}
**Historical data on first connection:**
Harmony pulls up to 90 days of historical sign-in and content activity when you first connect Box. After that, activity is kept in sync automatically every hour. Box itself retains one year of enterprise event history, so 90 days is a Harmony default rather than a Box limit.
{% endhint %}
***
#### Permissions Explained
Harmony requests two application scopes on the Box app. Both are read-only in practice - Harmony never writes to your Box account.
| Box permission | Purpose |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Manage users** | List the enterprise user directory - names, login emails, roles, account status, storage, and seat type |
| **Manage enterprise properties** | Read the enterprise event log, which is the source of both sign-in activity and content usage metrics |
{% hint style="info" %}
**Why "Manage" permissions for read-only data:**
Box does not offer read-only variants of these two scopes - the same permission that would allow changes is the one that allows listing. Harmony only ever issues read requests against your Box account.
{% endhint %}
Beyond the app's scopes, Box applies the authorizing person's own permissions on top. This is why an admin or co-admin is required: the scopes cap what the token *may* do, and the user's own role caps it further.
***
#### Use Cases
License Optimization
Identify Box seats that are assigned but unused. Each user's license tier is visible alongside their last sign-in and their daily content activity, so you can tell the difference between a seat that is quiet this week and one that has never been touched, and reclaim accordingly.
Access Reviews
See exactly who holds Admin and Co-Admin privileges in your Box enterprise. Box's own role names are preserved verbatim, so what you review in Harmony is what your Box administrator sees in the Box Admin Console.
Usage Insights
Track adoption by measuring real content interactions per user per day, broken down by action type - so you can distinguish heavy uploaders from occasional viewers, and see whether a department has genuinely adopted Box or merely been provisioned for it.
Offboarding Assurance
Spot Box accounts that are still active for people who have left, and confirm that seats were actually released rather than just marked inactive.
***
#### Troubleshooting
Data is not appearing after connection
**Possible causes:**
* The initial sync has not completed yet (may take up to 15 minutes)
* The person who authorized the connection is not a Box enterprise admin or co-admin
* The Box account is not on a plan that includes the enterprise event log
* The Box app is missing the **Manage users** or **Manage enterprise properties** permission
**Solutions:**
1. Wait up to 15 minutes for the initial sync to complete
2. Confirm the authorizing user's role in the Box Admin Console under **Users & Groups**
3. Disconnect and reconnect the integration using an admin or co-admin account
4. If your organization requires apps to be approved, ask your Box administrator to confirm the Harmony app is authorized in the Box Admin Console under **Apps** > **Custom Apps Manager**
User inventory syncs but activity data is empty
**Possible causes:**
* The **Manage enterprise properties** permission was not granted - the user directory needs only **Manage users**, so inventory can succeed while the event log is refused
* The authorizing admin lacks the **Run new reports and access existing reports** permission that Box requires for the enterprise event log
**Solutions:**
1. Verify the authorizing account holds the reporting permission in the Box Admin Console
2. Disconnect and reconnect the integration to re-grant both permissions
Admin sign-ins are missing from activity
**Possible causes:**
* Harmony counts standard Box sign-ins. Box records access to the Admin Console as a separate event type, which Harmony deliberately does not count to avoid reporting administrators as signing in twice for a single session
**Solutions:**
1. This is expected. An administrator who also uses Box normally will show sign-in activity as usual; one who only ever opens the Admin Console may show none
External collaborators are not listed
**Possible causes:**
* Harmony syncs your managed Box users only. External collaborators belong to their own Box enterprise and consume a seat there, not in yours
**Solutions:**
1. This is expected and keeps your seat count accurate
License tier shows as Unknown
**Possible causes:**
* Box does not expose a per-user license SKU. Harmony reports whether an account occupies an enterprise seat rather than guessing a plan name, and reports Unknown rather than a guess when that cannot be determined
**Solutions:**
1. Reconnect the integration with an admin account so the full user record, including enterprise membership, can be read
Recent activity takes a while to appear
**Possible causes:**
* Box's enterprise event log favours completeness over immediacy, so an event can surface in the log some time after it happened
**Solutions:**
1. Allow up to a few hours for very recent activity to appear. This is a Box platform behaviour, not a Harmony sync delay
***
#### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Harmony accesses Box data in read-only mode and does not modify any data in your Box account
* Harmony reads user directory and activity metadata only - it does not read, download, or index the contents of your files
* Integration can be revoked at any time from Box or Harmony settings
---
# 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/saas-applications/box.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.