# Miro setup for PopMCP

You end up pasting the Client ID and Client secret of a Miro app you create in your own Developer team.

- Auth: OAuth authorization
- Setup time: 6 min
- API base URL: https://api.miro.com/v2
- Credentials screen: https://miro.com/app/settings/user-profile/apps
- Provider docs: https://developers.miro.com/docs/getting-started-with-oauth

## Before you begin

- A Miro account. The Free plan is enough to create an app.
- A Developer team. Miro creates one at no cost the first time you build an app.
- An Enterprise plan if you need the organizations:read and organizations:teams:read scopes
- PopMCP's callback URL copied, ready to paste as the app's redirect URI

## Get your credentials

### 1. Open Your apps

Click your avatar in the top right, choose Settings, then open the Your apps tab. Click + Create new app.

Screen: https://miro.com/app/settings/user-profile/apps

### 2. Name the app and enable expiring tokens

In the Create new app modal, type `PopMCP` in App name and tick Expire user authorization token. Click Create app.

### 3. Add the redirect URI

On the app settings page, scroll to Redirect URI for OAuth2.0, paste PopMCP's callback URL and click Add. The URI must match what PopMCP sends, character for character.

### 4. Tick the permission scopes

Scroll to Permissions and tick `boards:read`, `boards:write`, `identity:read` and `team:read`. Leave the `organizations:*` boxes clear unless your account is on Enterprise.

### 5. Copy the Client ID and Client secret

Open App Credentials on the same page and copy Client ID and Client secret into the matching PopMCP fields. Save, then run the connect flow.

Screen: https://miro.com/app/settings/user-profile/apps

## Fields PopMCP asks for

- Auth type (connectionType): Create an app at miro.com/app/settings → "Create new app". Keep "Expiring token" enabled (the default) so access refreshes automatically, and enable the boards:read + boards:write scopes (plus organizations/teams scopes for Enterprise admin).
- Client ID (clientId) [required]: Your app's "Client ID" from its App settings page on miro.com.
- Client secret (clientSecret) [required]: Your app's "Client secret" from its App settings page. Stored encrypted; used server-side only and never shown again.

## Callback URL to register

https://app.popmcp.com/api/providers/miro/callback

## Scopes requested

- boards:read
- boards:write
- identity:read
- team:read
- team:write
- organizations:read
- organizations:teams:read

## Verify

After the OAuth redirect completes, PopMCP shows the Miro connector as Connected with your Miro name attached, and asking it to list boards returns the boards in your team.

## Troubleshooting

### redirect_uri_mismatch during the connect flow

Cause: The redirect URI on the Miro app does not exactly match the callback URL PopMCP sends.

Fix: Re-copy PopMCP's callback URL and add it verbatim under Redirect URI for OAuth2.0. Scheme, host, path and any trailing slash all have to match.

### The connection stops working after about an hour

Cause: The app was created without Expire user authorization token ticked, so Miro never issued a refresh token.

Fix: That checkbox is fixed at creation time and cannot be edited afterwards. Create a new app with it ticked, move the redirect URI and scopes over, then reconnect.

### Authorisation fails when organizations scopes are requested

Cause: The organizations:read and organizations:teams:read scopes are Enterprise only.

Fix: Untick those scopes under Permissions unless your Miro account is on Enterprise, then reconnect.

### The app does not appear in your normal team

Cause: Apps are created inside a Developer team, which is separate from your working team.

Fix: Install the app to the team whose boards you want to reach using Install app and get OAuth token.

### 429 Too Many Requests on bulk board edits

Cause: The app hit Miro's per-minute credit ceiling.

Fix: Slow the run down and batch item creation. Creating or updating an item is a Level 2 call at 100 credits and 1,000 per minute, and deleting one is Level 3 at 500 credits and 200 per minute.

---

Source: https://www.docs.popmcp.com/docs/integrations/miro/