Miro Developer Platform

Enhance Miro to fit the way you work

Automate, extend, and customize Miro to fit your teamwork.
Create Apps that combine Rest API, Webhooks and Web-Plugins.
Bring your collaboration to the next level.

Get Started

Boards picker

Miro Boards Picker allows your users to share links to their boards with your application — without using OAuth or APIs. Web developers can incorporate Picker API just with a snippet of Javascript code.

Miro Boards Picker provides next scenarios:
1) select — allows users to get board info and a direct link for the selected board.
2) access-link — allows users to get special access-link for the selected board and embed it on the website via iframe.
3) access-link & allowCreateAnonymousBoards — allow not registered in Miro users to create a new board and embed it on the website via iframe. See the instruction here.

Embedded boards get changes in realtime.

Demo

The source code of this demo is here.

Please note, that access-links generated in this example can't be pasted into your sites, because of your site domain not in domains whitelist.

Setup

1) Create an app for your Miro team.
2)Contact us to use Boards Picker. Provide 'clientId' of the application as a comment to the form.
3) In the app's settings provide the domain names where your Boards Picker is hosted. This lets us stop other websites from trying to impersonate your app. If you're developing locally, you can use localhost as the domain name as well.
4) Add the following JavaScript snippet in your HTML.

<script type="text/javascript" src="https://miro.com/app/static/boardsPicker.1.0.js"></script>

<script>
  function onSomeButtonClick() {
    miroBoardsPicker.open({
      clientId: 'client_id_from_your_app',
      action: 'select',
      success: function (result) {
        console.log(result)
      }
    })
  }
</script>

Using Boards Picker from JavaScript

Call miroBoardsPicker.open() method to open Boards Picker. Note that the Picker opens in a pop-up window, so call this function from within a user-triggered event (click or tap). Otherwise, the browser will block the pop-up.

Method open takes a single options parameter with the following fields:

options = {
    // Required. ClientId from your app
    clientId: 'string', 
  
    // Required. Define mode of Boards Picker.
    action: "select" // or "access-link"
  
    // Required. Called when a user selects an board in the Picker.
    success: function(selectedBoard) {
        console.log(selectedBoard)
    },

    // Optional. Called when the user closes the pop-up.
    cancel: function() {
    },
      
    // Optional. Called when something went wrong.      
    error: function() {
    },

    windowRef: windowRef, // Optional. Link to an already opened popup window. See example below in case you want lazy loading for boardsPicker.js. 
};

Handling the response.
Callback success returns info of selected board.

//when action is 'select'
selectedBoard = {
    id: "o9J_687XKf0="name: "Demo board"
    description: "Description for the demo board"
    viewLink: "https://miro.com/app/board/o9J_687XKf0=/"
}

//when action id 'acccess-link'
selectedBoard = {
    id: "o9J_687XKf0="name: "Demo board"
    description: "Description for the demo board"
    viewLink: "https://miro.com/app/board/o9J_687XKf0=/"
    accessLink: "https://miro.com/app/...."
    embedHtml: "<iframe src='https://miro.com/app/...'></iframe>"
}

Editable boards for anonymous users

Allow BoardsPicker to create boards for not registered users.

  • Set allowCreateAnonymousBoards=true.
  • Provide JWT token for BoardsPicker from your backend-side. This token used to create new boards on behalf of your integration.
function onClick() {
	miroBoardsPicker.open({
		clientId: '...', // 1) Put your 'clientId' here.
		action: 'access-link',
		allowCreateAnonymousBoards: true, //2) Enable this option 
		getToken: () => getTokenFromServer(), // Provide token in async way
		success: data => {
			console.log('on success', data)
			document.querySelector('#container').innerHTML = data.embedHtml
		},
		error: e => {
			console.log('on error', e)
		},
		cancel: () => {
			console.log('on cancel')
		},
    
		windowRef: windowRef, // Optional. Link to an already opened popup window. See example below in case you want lazy loading for boardsPicker.js. 
	})
}

// Type: () => Promise<string>
function getTokenFromServer() {
	//Get JWT token from your server. Read more about JWT https://jwt.io/
	return fetchPost('https://example.com/token-for-integration-with-miro')
}

Generate JWT on your backend.

  • Get lib for your server language from https://jwt.io/
  • Use Client id for iss field in payload data
  • Use Client secret with HMAC256 algorithm for Signing token
  • We recommend setting a token expiration date of no more than 24 hours (exp field in payload data)

Example for Java using Auth0 library

JWT.create()
  .withIssuer("CLIENT_ID")
  .withExpiresAt(new Date(System.currentTimeMillis() + TimeUnit.MINUTES.toMillis(5)))
  .sign(Algorithm.HMAC256("CLIENT_SECRET"));
  • Add endpoint like
POST https://example.com/token-for-integration-with-miro

This endpoint should return JWT

Do not generate a token on client-side and please ensure that your endpoint signed by your user authorization token. Such tokens may be easily compromised.

But no need to generate JWT per user, you can regenerate it per timeout.

Lazy loading boardsPicker.js example

async function onClick() {

	//calc popup window size and position
	const pos = {left, top}  
	const size = {width, height} 

	const windowRef = window.open(
		'',
		'_blank',
		`width=${size.width},height=${size.height},left=${pos.left},top=${pos.top},menubar=0,toolbar=0,location=0,personalbar=0,status=0`
	)

	await loadScript('https://miro.com/app/static/boardsPicker.1.0.js') // Lazy loading for boardsPicker script 

	miroBoardsPicker.open({
		windowRef: windowRef, //Provide opened window reference
		clientId: '...',
		// ... rest params
	})
}

Troubleshooting

If your website has a policy for blocking referrer information, Embed via access-link will not load. To fix this, you can override the referrerpolicy attribute for the iframe tag on your site.

<iframe src="https://miro.com/app/..." referrerpolicy="no-referrer-when-downgrade"></iframe>

Questions

For technical questions or bug reports please use our Developer Forum.
If you want to discuss partnership opportunities, please fill this form.

Updated 4 months ago


Boards picker


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.