# Connect Miro

An account of Miro is connected once, on the instance, by a person who then gives missions access to its resources; the agent never receives the credential. Miro boards: sticky notes, shapes, texts, cards, frames, connectors and tags — one resource per board.

One account is the access token of a Miro app installed on one team; one resource is one board of that team. A mission touches only the boards it was given. Miro boards have no environment: adding and editing, adding many items at once, deleting an item and deleting a frame are separate permissions instead.

Permissions, presets and tools of this service: [Miro plugin](/plugins/miro).

## How to connect

On the instance: Accounts → Connect an account, then pick the service. A company app, when the service needs one, is registered once by an administrator under Settings → Administration → Company apps, or set in the configuration (`providers.<id>.*`, see [configuration keys](/docs/configuration/keys)). Every instance registers its own app: this gateway never uses an app shared with another one.

### The usual way: with a access token of a Miro app pasted by hand

1. In Miro, open your avatar, Settings, Your apps, and create a new app (Miro asks for a Developer team).
2. Leave 'Expire user authorization token' unchecked: an expiring token stops working after one hour, and the choice cannot be changed once the app exists.
3. Give the app the scopes boards:read and boards:write, and no other.
4. Choose Install app and get OAuth token, pick the team that holds the boards, authorise, and copy the access token here.

Where: [https://miro.com/app/settings/user-profile/apps](https://miro.com/app/settings/user-profile/apps)

Permissions to grant at the service, and no more:

- boards:read: read
- boards:write: read-write

What the connect page asks:

- Access token (secret): Create a Miro app with only boards:read and boards:write, leave 'Expire user authorization token' unchecked, and install it on the team whose boards the agents may work on. boards:write also lets the token delete boards and manage board members; the gateway limits what agents do with it, not the token itself.

The service's documentation: [https://developers.miro.com/docs/rest-api-build-your-first-hello-world-app](https://developers.miro.com/docs/rest-api-build-your-first-hello-world-app)

## Disconnecting

In Miro, open Settings, Your apps, and delete the app or uninstall it from the team; its token stops working.

## Registration notes from the plugin

From the plugin's [README](https://github.com/vaubaan/gateway/blob/main/plugins/miro/README.md), written for the people who register the app or create the token.

### Credential and resources

Kind `api-key`, one secret field `access_token`: the access token of a Miro
app with the scopes `boards:read` and `boards:write` only, created with
**"Expire user authorization token" unchecked** (an expiring token stops
after one hour, and its refresh needs the app's client secret). Pattern
`^[A-Za-z0-9._~+/=-]{20,512}$`; `verify` reads the token context
(`GET /v1/oauth-token`), names the account after the team, and refuses a
token without both scopes. `boards:write` also lets the token delete boards
and manage members: no tool of the plugin does either.

`discoverResources` reads the team from the token context, then
`GET /v2/boards?team_id=…`, 50 a page, **at most 500 boards**
(`MAX_DISCOVERED_BOARDS`). One resource per board: `ref` is the board id
with its trailing `=` written `~` (`uXjVOD6LSME=` → `uXjVOD6LSME~`),
`displayName` its name, `metadata` the team id and the view link. A board
id outside Miro's grammar is left out, with a warning.