> 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/miro.md).
# Miro
Harmony's Miro integration connects your Miro organization to give you visibility into who holds a Miro license, which tier they are on, and how often they actually sign in. Once connected, Harmony syncs your Miro data automatically so you can spot unused seats, review access, and understand adoption alongside the rest of your SaaS portfolio.
#### What the Miro integration enables
| Capability | Description |
| ------------------------ | ----------------------------------------------------------------------------- |
| License Tier Visibility | See each user's license tier (Paid, Free, or Unknown) alongside activity data |
| Login Trends | Track sign-in activity over time to understand adoption and spot drop-offs |
| Access Review | Review each member's Miro role - in Miro's own terms - during access reviews |
| Offboarding Verification | Confirm departed employees no longer hold an active Miro seat |
***
#### Prerequisites
1. **A Miro Enterprise plan** - the APIs Harmony uses are available only on Enterprise. Miro's other plans do not expose organization members or audit logs.
2. **Company Admin role in Miro** - required both to see the Enterprise permissions when creating the app and to authorize it
3. **A Harmony account** with admin privileges
{% hint style="warning" %}
**Why you create the app yourself**
Miro grants Enterprise permissions only to an app that belongs to an Enterprise organization. A shared, vendor-owned app cannot request them on your behalf - Miro silently ignores the request. You therefore create the app inside your own Miro organization and provide Harmony with the resulting token.
{% endhint %}
***
#### Connect Miro to Harmony
**Step 1: Create a Miro app**
1. Sign in to Miro as a **Company Admin**
2. Click your account avatar and select **Settings**
3. Open the **Your apps** tab
4. Click **+ Create new app**
5. Name the app (for example, `Harmony Integration`)
6. Leave the **Expire user authorization token** checkbox **unchecked**
7. Click **Create app**
{% hint style="danger" %}
**Do not enable "Expire user authorization token."**
With that option enabled, the token Miro issues stops working after one hour and the integration silently stops syncing. Left unchecked, Miro issues a non-expiring token, which is what Harmony needs - there is no re-authorization prompt to catch an expired one.
Miro locks this setting once the app is created - it cannot be changed afterwards. If you enable it by mistake, the only fix is to create a new app.
{% endhint %}
**Step 2: Grant the required permissions**
In the app's **Permissions** section, select these two scopes, both listed under **Enterprise plan only**:
* `organizations:read`
* `auditlogs:read`
See [Permissions Explained](#permissions-explained) for what each one is used for.
{% hint style="info" %}
If these scopes are not listed, your Miro organization is not on an Enterprise plan, or your account does not hold the Company Admin role. Both conditions must be met for Miro to show them.
{% endhint %}
**Step 3: Install the app and copy the token**
1. At the bottom of the app settings page, click **Install app and get OAuth token**
2. From the **Select a team** drop-down menu, select a team, then click **Install & authorize**
3. Copy the access token that Miro displays
Treat this token like a password - it grants read access to your organization's member list and audit log.
**Step 4: Connect in Harmony**
1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Miro** under **SaaS Applications** and click **Connect**
4. Paste the access token
5. Click **Save**
Harmony begins syncing immediately. Up to 30 days of historical sign-in activity is pulled in on the first connection, and your member list refreshes every 6 hours.
***
#### Permissions Explained
**Required scopes**
Both scopes are **Enterprise plan only** in Miro.
| Scope | Miro's description | Purpose |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `organizations:read` | Retrieve information about the organization, such as name, plan, number of licenses, organization settings, or organization members | List organization members with their email, license tier, and role - the basis for license optimization |
| `auditlogs:read` | Read audit logs for this team's organization | Read sign-in events to build login trends and identify inactive users |
Harmony uses both in read-only mode and never modifies anything in your Miro organization.
{% hint style="info" %}
**Both scopes are needed**
Harmony builds its Miro user list only from the organization members endpoint. Without `organizations:read`, no members are synced and sign-in events have no member records to attach to, so license tier, roles, and login trends are all unavailable. Without `auditlogs:read`, members, license tier, and roles still sync, but there is no sign-in history behind them.
{% endhint %}
***
#### What Harmony Syncs from Miro
| Data | Description |
| -------------------- | ----------------------------------------------------------------------------------- |
| Organization members | Email address and whether the account is active |
| License tier | Paid, Free, or Unknown, plus the license name Miro reports |
| Roles | Each member's organization role, reported in Miro's own terms |
| Sign-in activity | Every successful sign-in Miro records in its audit log, kept as an individual event |
| Last activity | The most recent activity timestamp Miro reports for each member |
Miro's organization members API returns no display name, so Miro users appear in Harmony without one and are identified by their email address.
{% hint style="info" %}
**Where to find Miro data in Harmony:**
* **Applications** - Miro appears as a discovered application with license and adoption details
* **People** - each employee's profile shows their Miro license tier, role, and last sign-in
{% endhint %}
{% hint style="info" %}
**Historical data on first connection:**
Harmony pulls up to 30 days of sign-in history when you first connect Miro. After that, sign-in activity is checked hourly and stays in sync automatically.
Miro's audit log keeps only the last 90 days of events, so sign-in activity older than that cannot be retrieved through the API at all - Miro's CSV export in the Miro admin UI is the only way to reach it.
{% endhint %}
***
#### Use Cases
License Optimization
Find members holding a paid Miro license who have not signed in recently, and reclaim or downgrade those seats. License tier is shown next to sign-in activity so the decision does not require cross-referencing two systems.
Access Review
Review who has access to your Miro organization and at what role, using Miro's own role names, as part of periodic access certification.
Offboarding Verification
Confirm that departed employees no longer appear as active members of your Miro organization.
Adoption Tracking
Follow login trends over time to see whether Miro adoption is growing or falling off.
***
#### Troubleshooting
The integration stopped syncing about an hour after connecting
**Possible cause:**
* The **Expire user authorization token** option was enabled when the app was created, so Miro issued a token valid for one hour
**Solution:**
Miro locks this setting after the app is created, so it cannot be turned off on the existing app. Create a replacement:
1. Create a new app in Miro with **Expire user authorization token** left unchecked
2. Grant `organizations:read` and `auditlogs:read`
3. Install the app, copy the new token, and update the credentials in Harmony
4. Uninstall the old app from your Miro team
The Enterprise permissions are not shown when creating the app
**Possible causes:**
* Your Miro organization is not on an Enterprise plan
* Your Miro account does not hold the Company Admin role
**Solutions:**
1. Confirm your organization is on an Enterprise plan
2. Confirm your account is a Company Admin, then reload the app settings page
3. If both are true and the scopes are still missing, contact Miro support with your app's Client ID
Harmony will not accept the token even though you are a Company Admin on Enterprise
**Possible cause:**
* Your organization is on Enterprise, but Miro has not switched on API access for it, so the Enterprise endpoints reject the token and Harmony refuses to save it
**Solution:**
1. Ask Miro to enable Enterprise API access for your organization using their request form:
2. Once Miro confirms it is enabled, re-mint the token and connect again in Harmony
Users appear but license tier shows as Unknown
**Possible cause:**
* The member holds a Miro license type whose billing status Miro does not publish, so Harmony cannot classify it as paid or free
**Solution:**
1. No action is needed to identify the seat - the license name Miro reports is always shown alongside the tier
No Miro users appear in Harmony
**Possible cause:**
* The token was minted without `organizations:read`, so the organization member list does not sync - and it is the only source of Miro users in Harmony, so sign-in activity on its own produces none
**Solution:**
1. Grant `organizations:read` on the app, reinstall it, and update the token in Harmony - the full member list, including members who have never signed in, then syncs
Data stopped updating
**Possible cause:**
* The app was uninstalled from your Miro team, which invalidates its token
**Solution:**
1. Reinstall the app in Miro, copy the new token, and update the credentials in Harmony
***
#### Disconnect Miro from Harmony
1. Log in to your Harmony dashboard
2. Go to **Settings** > **Integrations**
3. Find **Miro** under **SaaS Applications** and click the integration card
4. Click **Disconnect** and confirm
Harmony stops syncing data from Miro. Previously synced data remains available in Harmony.
To revoke access from the Miro side as well, uninstall the app from your Miro team settings.
***
#### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Harmony accesses Miro data in read-only mode and does not modify anything in your Miro organization
* Only member details, license information, and sign-in events are collected - board contents are never accessed
* Access can be revoked at any time from Harmony settings or by uninstalling the app in Miro
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.harmony.io/integrations/saas-applications/miro.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.