> 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`) and select the team that owns it
6. Leave the **Expire user authorization token** checkbox **unchecked**

{% 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, the token remains valid until the app is uninstalled from your team.

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, the app is owned by a team that is not on an Enterprise plan, or you are not a Company Admin of that team. Both conditions must be met for Miro to show them.
{% endhint %}

**Step 3: Install the app and copy the token**

1. Click **Install app and get OAuth token**
2. Select the organization to install into and confirm
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" %}
**If only `auditlogs:read` is granted**

Harmony still discovers users who have signed in, and login trends work normally. What is missing is license tier, roles, and any member who has not signed in during the reporting window - which is usually the seat you most want to find. Granting `organizations:read` is what makes license optimization possible.
{% 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     | Login events per user, recorded once per user per day           |
| Last activity        | The most recent activity timestamp Miro reports for each member |

{% 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.
{% endhint %}

***

#### Use Cases

<details>

<summary>License Optimization</summary>

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.

</details>

<details>

<summary>Access Review</summary>

Review who has access to your Miro organization and at what role, using Miro's own role names, as part of periodic access certification.

</details>

<details>

<summary>Offboarding Verification</summary>

Confirm that departed employees no longer appear as active members of your Miro organization.

</details>

<details>

<summary>Adoption Tracking</summary>

Follow login trends over time to see whether Miro adoption is growing or falling off, and by which teams.

</details>

***

#### Troubleshooting

<details>

<summary>The integration stopped syncing about an hour after connecting</summary>

**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

</details>

<details>

<summary>The Enterprise permissions are not shown when creating the app</summary>

**Possible causes:**

* The team that owns the app is not on a Miro Enterprise plan
* Your Miro account does not hold the Company Admin role on that team

**Solutions:**

1. Confirm the owning team 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

</details>

<details>

<summary>Users appear but license tier shows as Unknown</summary>

**Possible causes:**

* The token was issued without the `organizations:read` permission, so members are discovered from sign-in activity only
* The member holds a Miro license type whose billing status Miro does not publish

**Solutions:**

1. Verify the app has `organizations:read` granted, then reinstall the app and update the token in Harmony
2. If the permission is present, the license name Miro reports is still shown alongside the tier

</details>

<details>

<summary>Some members are missing</summary>

**Possible cause:**

* The token lacks `organizations:read`, so only members with recent sign-in activity are discovered

**Solution:**

1. Grant `organizations:read`, reinstall the app, and update the token in Harmony - the full member list, including members who have never signed in, then syncs

</details>

<details>

<summary>Data stopped updating</summary>

**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

</details>

***

#### 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

<details>

<summary>Key privacy principles</summary>

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

</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 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=<question>&goal=<endgoal>
```

`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.