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.
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). 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
- In Miro, open your avatar, Settings, Your apps, and create a new app (Miro asks for a Developer team).
- Leave 'Expire user authorization token' unchecked: an expiring token stops working after one hour, and the choice cannot be changed once the app exists.
- Give the app the scopes boards:read and boards:write, and no other.
- 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
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
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, 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.