board.Board

board is a property of window.miro that enables:

Table of contents

Properties

Methods

Properties

ui

ui: BoardUI

ui is the namespace that groups the methods to interact with the board UI.


notifications

notifications: Notifications

notifications is the namespace that groups methods to handle and control notifications displayed on the board UI.
Through miro.board.notifications, apps can access methods to display specific notification types, and to populate them with the desired messages.

  • showInfo: a convenience method to trigger a notification to display an informative message on the board UI.
    Informs users about the successful outcome of an action or event.
  • showError: a convenience method to trigger a notification to display an error message on the board UI.
    Warns users about an unexpected error that caused the action or event to partially or completely fail.
  • show: a method that triggers a notification to display either an informative, or an error message on the board UI.

viewport

viewport: Viewport

viewport is the namespace that groups methods to:

  • get the current viewport.
  • set a new viewport.
  • zoomTo an item on the board, and focus the viewport on the specified object.

Methods

createCard

createCard(props?): Promise<Card>

Creates a card on a board.

There are no required properties that you need to pass upon creation.
If you create a card without passing any properties, the card is empty.
You can update the default values at a later time.

Example:

const card = await miro.board.createCard({
  title: 'This is an easy task',
  description: 'Paint wall. Watch paint dry.',
  dueDate: '2025-08-18',
  assignee: {
    userId: '3074457356556531234',
  },
  style: {
    cardTheme: '#2d9bf0', // Default color: light blue
  },
  x: 0, // Default value: horizontal center of the board
  y: 0, // Default value: vertical center of the board
  width: 320,
  rotation: 0.0,
});

console.log(card);

Card item, compact view:

Compact view of a card. You can view only basic information.Compact view of a card. You can view only basic information.
Figure 1. Compact view of a card. You can view only basic information.

Card item, detail view:

Detail view of a card. You can view and edit all the card fields.Detail view of a card. You can view and edit all the card fields.
Figure 2. Detail view of a card. You can view and edit all the card fields.

Parameters

NameType
props?CardProps

Returns

Promise<Card>


createAppCard

createAppCard(props?): Promise<AppCard>

Creates an app card on a board.

There are no required properties that you need to pass upon creation.
If you create a card without passing any properties, the card is empty.
You can update the default values at a later time.

ℹ️ Note:

  • To open the detail view of an app card from its compact view, the app must listen to the app_card:open event.
    A typical use case for app_card:open is to open a modal displaying content fetched from a specified URL.
    For more information, see app_card:open.

Example:

const appCard = await miro.board.createAppCard({
  title: 'This is the title of the app card',
  description:
    'The custom preview fields are highlighted in different colors; the app card icon is displayed on the bottom-right.',
  style: {
    cardTheme: '#2d9bf0',
  },
  fields: [
    {
      value: 'Owner',
      iconUrl: 'https://cdn-icons-png.flaticon.com/512/921/921124.png',
      iconShape: 'round',
      fillColor: '#FBE983',
      textColor: '#F83A22',
      tooltip: 'Caption text displayed in a tooltip when clicking or hovering over the preview field',
    },
    {
      value: 'Timeline',
      iconUrl: 'https://cdn-icons-png.flaticon.com/512/3094/3094861.png',
      iconShape: 'square',
      fillColor: '#F8D878',
      textColor: '#503000',
      tooltip: 'Caption text displayed in a tooltip when clicking or hovering over the preview field',
    },
    {
      value: 'Tasks',
      iconUrl: 'https://cdn-icons-png.flaticon.com/512/3176/3176366.png',
      iconShape: 'square',
      fillColor: '#bef2f2',
      textColor: '#0713FF',
      tooltip: 'Caption text displayed in a tooltip when clicking or hovering over the preview field',
    },
    {
      value: 'Bug fix',
      iconUrl: 'https://cdn-icons-png.flaticon.com/512/3867/3867669.png',
      iconShape: 'square',
      fillColor: '#E5E5E5',
      textColor: '#000000',
      tooltip: 'Caption text displayed in a tooltip when clicking or hovering over the preview field',
    },
  ],
  x: 2000,
  y: 2000,
  width: 320,
  rotation: 0.0,
  status: 'connected', // Default status of new app cards: 'disconnected'
});

// Listen to the 'app_card:open' event
miro.board.ui.on('app_card:open', (event) => {
  console.log('Subscribed to app card open event', event);
  const {appCard} = event;

  // Fetch a specific app card by specifying its ID
  const url = `https://my.app.example.com/modal.html?appCardId=${appCard.id}`;

  // Open the modal to display the content of the fetched app card
  miro.board.ui.openModal({
    url,
  });
});

// Output the created item to the developer console
console.log(appCard);

App card item, compact view:


Figure 1. Compact view of an app card. The custom preview fields are highlighted in different colors. The default app card icon is on the bottom right. The status icon is displayed when hovering the mouse over the top-right corner of the app card.

Parameters

NameType
props?AppCardProps

Returns

Promise<AppCard>


createFrame

createFrame(props?): Promise<Frame>

Creates a frame on a board.

There are no required properties to pass upon creation.
You can update the default values at a later time.

Example:

const frame = await miro.board.createFrame({
  title: 'This frame ratio is 16:9',
  style: {
    fillColor: '#ffffff', // Default value: 'transparent' (no fill color)
  },
  x: 0, // Default value: horizontal center of the board
  y: 0, // Default value: vertical center of the board
  width: 800,
  height: 450,
});

console.log(frame);

Frame item:

A frame parent item containing a sticky note as a child item.A frame parent item containing a sticky note as a child item.
Figure 1. A frame parent item containing a sticky note as a child item.

Parameters

NameType
props?FrameProps

Returns

Promise<Frame>


createImage

createImage(props): Promise<Image>

Inserts an image on a board.

The only required property to pass upon creation is a valid url pointing to the image.

Example:

const image = await miro.board.createImage({
  title: 'This is an image',
  url: 'https://miro.com/organize-miro-boards.svg',
  x: 0, // Default value: horizontal center of the board
  y: 0, // Default value: vertical center of the board
  width: 800, // Set either 'width', or 'height'
  rotation: 0.0,
});

console.log(image);

Image item:


Figure 1. Image item.

Parameters

NameType
propsImageProps

Returns

Promise<Image>


createPreview

createPreview(props): Promise<Preview>

Creates a preview on a board.

The only required property to pass upon creation is a valid url.

Example:

const preview = await miro.board.createPreview({
  url: 'https://miro.com/',
  x: 0, // Default value: horizontal center of the board
  y: 0, // Default value: vertical center of the board
  width: 400,
  rotation: 0.0,
});

console.log(preview);

Preview item:

Preview item.Preview item.
Figure 1. Preview item.

Parameters

NameType
propsPreviewProps

Returns

Promise<Preview>


createShape

createShape(props?): Promise<Shape>

Creates a geometric shape on a board.

The only required property to pass upon creation is a valid shape.

Example:

const shape = await miro.board.createShape({
  content: '<p>This is a star shape.</p>',
  shape: 'star',
  style: {
    fillColor: '#fbff00', // Default color: transparent (no fill)
    fontFamily: 'arial', // Default font type for the text
    fontSize: 14, // Default font size in dp for the text
    textAlign: 'center', // Default alignment: center
    textAlignVertical: 'middle', // Default alignment: middle
  },
  x: 0, // Default value: center of the board
  y: 0, // Default value: center of the board
  width: 200,
  height: 200,
});

console.log(shape);

Shape item (star shape):

Shape item example: a star shape.Shape item example: a star shape.
Figure 1. Shape item example: a star shape.

Parameters

NameType
props?ShapeProps

Returns

Promise<Shape>


createStickyNote

createStickyNote(props?): Promise<StickyNote>

Creates a sticky note on a board.
Sticky notes look like physical paper sticky notes.

There are no required properties that you need to pass upon creation.
If you create a sticky note without passing any properties, the sticky note content is empty.
You can update the default values at a later time.

Example:

const stickyNote = await miro.board.createStickyNote({
  content: '<p>This is a sticky note. It looks just like the actual paper one.</p>',
  style: {
    fillColor: 'light_yellow', // Default value: light yellow
    textAlign: 'center', // Default alignment: center
    textAlignVertical: 'middle', // Default alignment: middle
  },
  x: 0, // Default value: horizontal center of the board
  y: 0, // Default value: vertical center of the board
  shape: 'square',
  width: 200, // Set either 'width', or 'height'
});

console.log(stickyNote);

Sticky note item:


Figure 1. Sticky note item.

Parameters

NameType
props?StickyNoteProps

Returns

Promise<StickyNote>


createText

createText(props?): Promise<Text>

Creates a text item on a board.

There are no required properties to pass upon creation.
If you create a text item without passing any properties, content is an empty string.
You can update the values at a later time.

Example:

const text = await miro.board.createText({
  content: '<p>This is a piece of text to remind me that I always finish what I ...</p>',
  style: {
    fillColor: 'transparent', // Default value: transparent (no fill)
    fillOpacity: 1, // Default value: 1 (solid color)
    fontFamily: 'arial', // Default font type for the text
    fontSize: 14, // Default font size for the text
    textAlign: 'left', // Default alignment: left
  },
  x: 0, // Default value: horizontal center of the board
  y: 0, // Default value: vertical center of the board
  width: 300,
  rotation: 0.0,
});

console.log(text);

Text item:

Text item.Text item.
Figure 1. Text item.

Parameters

NameType
props?TextProps

Returns

Promise<Text>


createEmbed

createEmbed(props): Promise<Embed>

Creates an embed item on a board.

To embed content from a supported provider in a board, specify:

  • The URL pointing to the resource that you want to embed in a board.
  • (Optional):
    • x and y board coordinates where you want the content to be embedded.
    • width and height of the embed area.
    • A URL pointing to an image to use as a preview for the embed item.

ℹ️ Note:

  • If you don't explicitly set any dimensions, width and height are set based on the corresponding retrieved values for the resource.
  • If width and height values aren't available, the embed item is displayed on the board as a 500x500 dp gray square.

Example:

const embed = await miro.board.createEmbed({
  url: 'https://youtu.be/HlVSNEiFCBk',
  previewUrl:
    'https://miro.com/blog/wp-content/uploads/2020/10/organize-their-Miro-boards-for-trainings-and-workshops-FB.png',
  mode: 'modal',
  width: 1280,
  height: 720,
  x: 1600,
  y: 1600,
});

console.log(embed);

Embed item example:


Figure 1. Example of an embed item with a playable YouTube video and an assigned preview image.

Parameters

NameType
propsEmbedProps

Returns

Promise<Embed>


createConnector

createConnector(props): Promise<Connector>

Creates a connector item on a board.

When creating connector lines programmatically, either with the Web SDK or the REST API, it's not possible to create loose (both ends disconnected) or dangling (one end disconnected) connectors.
You must specify the x and y coordinates of both the start and end points of a connector line.
x and y accept numerical values between 0.0 and 1.0 included.

Example:

// Create a shape to use as a start point for the connector.
const start = await miro.board.createShape({
  content: 'start',
  x: 4500,
});

// Create a shape to use as an end point for the connector.
const end = await miro.board.createShape({
  content: 'end',
  x: 4800,
});

// Create a connector line.
const connector = await miro.board.createConnector({
  shape: 'elbowed',
  style: {
    startStrokeCap: 'diamond',
    endStrokeCap: 'stealth',
    strokeStyle: 'dashed',
    strokeColor: '#ff00ff', // Magenta
    strokeWidth: 2,
  },
  // Set the start point of the connector line.
  start: {
    // Define the start board item for the connector line by specifying the 'start' item ID.
    item: start.id,
    // Set a point on the border of the 'start' shape to mark the start point of the connector line.
    position: {
      // Horizontal: right
      x: 1.0,
      // Vertical: middle
      y: 0.5,
    },
  },
  // Set the end point of the connector line.
  end: {
    // Define the end board item for the connector line by specifying the 'end' item ID.
    item: end.id,
    // Set a point on the border of the 'end' shape to mark the end point of the connector line.
    position: {
      // Horizontal: left
      x: 0.0,
      // Vertical: bottom
      y: 1.0,
    },
  },
});

console.log(connector);

Connector example:


Figure 1. The connector line joins the start and end shapes. It starts from the point defined in start.position, and it ends at the point defined in end.position.

Parameters

NameType
propsConnectorProps

Returns

Promise<Connector>


createTag

createTag(props): Promise<Tag>

Creates a tag on a board.
After creating a tag, you can attach it to the following items:

ℹ️ Note:

  • title is required.
  • If no color is specified, it defaults to red.
  • Card and sticky note items can have up to 8 tags.
  • Boards can have up to 100 tags in total.

Example:

// Create a tag
const todo = await miro.board.createTag({
  title: 'todo or not todo, that is the question',
  color: 'yellow',
});

// Create a sticky note and attach the tag to it
const stickyNote = await miro.board.createStickyNote({
  content: "sticky note with tag: 'todo'",
  tagIds: [todo.id],
});

console.log(stickyNote.tagIds); // => ['3074457345627244742']

Tag attached to a sticky note:

A tag attached to a sticky note.A tag attached to a sticky note.
Figure 1. A tag attached to a sticky note.

Parameters

NameType
propsTagProps

Returns

Promise<Tag>


sync

sync(item): Promise<void>

sync propagates to the board any changes to item and tag properties.
After updating the properties of an item or a tag, sync it with the board to:

  • Propagate to the board the changes applied to the item or to the tag.
  • Make the changes visible on the board.

All board items and tags require sync to make any changes to their properties visible on the board.

For more information and examples, see Update and sync item properties.

Example:
(The code example updates a text item using sync.
The same mechanism applies to and works in the same way for all supported board items.)

// Create an item.
// In this case, a text item.
const text = await miro.board.createText({
  content: '<p>This is a piece of text to remind me that I always finish what I ...</p>',
  style: {
    fillColor: 'transparent',
    textAlign: 'left',
  },
  x: 0,
  y: 0,
  width: 450,
  rotation: 0.0,
});

// Update the board item by modifying the values of its properties.
// In the text item case, the updated properties modify content, background color, and rotation of the item.
text.content = 'A fourteneer is "A line that rumbles on like this for being a bit too long."';
text.style.fillColor = '#a9fe65';
text.rotation = 180.0;

// Call 'sync' to make the changed board item properties visible on the board.
await text.sync();

// Output the updated board item to the developer console.
console.log(text);

Example:
(The code example updates a tag using sync.
The same mechanism applies to and works in the same way for all supported board items.)

// Create a tag.
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create a sticky note and attach the tag to it.
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tag: "todo"',
  tagIds: [todo.id],
});
console.log(stickyNote.tagIds); // => ['3074457345627244742']

// Update the tag properties: title and color.
todo.title = "won't fix";
todo.color = 'green';

// Call 'sync' to make the changed tag properties visible on the board.
await todo.sync();

// Output the updated tag to the developer console.
console.log(todo);

Parameters

NameType
itemBaseMixin

Returns

Promise<void>


remove

remove(item): Promise<void>

Removes a board item or a tag from the board.
When removing board items or tags, any associated metadata is removed as well.

ℹ️ Note:

  • To use the remove() method, apps need the boards:write permission.
  • board.remove() removes board items and tags from the board.
    It doesn't remove parent-child relationships between items.
    To remove a parent-child relationship between items, use remove() at the parent item level.
    For example: frame.remove().

remove is common to all board items, except unsupported items.

Parameters

NameType
itemItem

Returns

Promise<void>


bringToFront

bringToFront(items): Promise<void>

In a stack of items, it brings an item or an array of items to the front, so that they are at the top of the stack.
When they are at the front, items are fully visible; they can partially or completely hide underlying items in the same stack.

ℹ️ Note:

  • Frame items don't support the bringToFront() method.
    Since they act as parent that can contain other items, they are always at the back, relative to any other items on the board.
    The only object behind a frame is the board itself.

Example:

// Create three sticky notes
const first = await miro.board.createStickyNote({
  content: 'first',
});

const second = await miro.board.createStickyNote({
  content: 'second',
});

const third = await miro.board.createStickyNote({
  content: 'third',
});

// Bring the first sticky note to the front of the board.
await miro.board.bringToFront(first);

// Or: bring the second and third sticky notes to the front of the board.
await miro.board.bringToFront([second, third]);

Parameters

NameType
itemsItems

Returns

Promise<void>


sendToBack

sendToBack(items): Promise<void>

In a stack of items, it sends an item or an array of items to the back, so that they are at the bottom of the stack.
When they are at the back, items are partially or completely hidden by overlying items in the same stack.

ℹ️ Note:

  • Frame items don't support the sendToBack() method.
    Since they act as parents that can contain other items, they are always at the back, relative to any other items on the board.
    The only object behind a frame is the board itself.

Example:

// Create three sticky notes
const first = await miro.board.createStickyNote({
  content: 'first',
});

const second = await miro.board.createStickyNote({
  content: 'second',
});

const third = await miro.board.createStickyNote({
  content: 'third',
});

// Send the first sticky note to the back of the board
await miro.board.sendToBack(first);

// Or: send the second and third sticky notes to the back of the board
await miro.board.sendToBack([second, third]);

Parameters

NameType
itemsItems

Returns

Promise<void>


getById

getById(id): Promise<BoardNode>

Fetches an item, if it exists on the board, based on the item ID that you pass with the method.
If the requested item ID doesn't exist—for example, because the item has been deleted from the board—the method throws an error:

Can not retrieve item with id 3458764518726781234

Example:

// Create a sticky note
const stickyNote = await miro.board.createStickyNote({
  content: 'This is a sticky note',
});

// Get the sticky note by passing its ID
await miro.board.getById(stickyNote.id);

Parameters

NameType
idstring

Returns

Promise<BoardNode>


get

get(filter): Promise<Card[]>

Fetches one or more items or tags from the board.
If you don't pass any arguments, the method returns an array with all the items and tags on the board.

Optionally, you can filter items by id, type, and tags:

  • Filter by id: pass an item or a tag id to fetch the corresponding item or tag.
    If the ID doesn't exist on the board, the method throws an error.
    Pass an array of IDs to fetch an array with all the items or tags matching one of the specified IDs.
  • Filter by type: pass an item type to fetch an array with the items matching the requested type.
    Pass an array of types to fetch an array with the items matching one of the specified types.
  • Filter by tags: pass one or more tags to fetch all the items with the specified tags.
    If the tags don't exist on the board, the method throws an error.
    Pass an array of tags to fetch an array with the items matching one of the specified tags.

ℹ️ Note:

  • When filtering with an array of item IDs, types, or tags, the logical operator between the array members is OR.
  • The method cannot return child items inside unsupported parent items, such as User Story Mapping (USM) and Kanban.

Example:

// Create a tag
const todo = await miro.board.createTag({
  title: 'todo',
  color: 'yellow',
});

// Create another tag
const urgent = await miro.board.createTag({
  title: 'urgent',
  color: 'magenta',
});

// Create a card and attach the tags to it
const card = await miro.board.createCard({
  title: 'card with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Create a sticky note and attach the tags to it
const stickyNote = await miro.board.createStickyNote({
  content: 'sticky note with tags: "todo", "urgent"',
  tagIds: [todo.id, urgent.id],
});

// Call 'sync' to make the attached tags visible on the items on the board
await card.sync();
await stickyNote.sync();

// Get the sticky note by passing its ID
await miro.board.get({
  id: stickyNote.id,
});

// Get all items with type: 'card' OR 'sticky_note'
await miro.board.get({
  type: ['card', 'sticky_note'],
});

// Get all 'card' OR 'sticky_note' items with tags: 'todo' OR 'urgent'
await miro.board.get({
  type: ['sticky_note', 'card'],
  tags: ['todo', 'urgent'],
});

Parameters

NameType
filter{ id: string | string[] } & { type: "card" } & { type?: string | string[] ; tags?: string | string[] } & { type: "card" }

Returns

Promise<Card[]>

get(filter): Promise<Frame[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "frame" } & { type?: string | string[] ; tags?: string | string[] } & { type: "frame" }

Returns

Promise<Frame[]>

get(filter): Promise<Image[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "image" } & { type?: string | string[] ; tags?: string | string[] } & { type: "image" }

Returns

Promise<Image[]>

get(filter): Promise<Preview[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "preview" } & { type?: string | string[] ; tags?: string | string[] } & { type: "preview" }

Returns

Promise<Preview[]>

get(filter): Promise<Shape[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "shape" } & { type?: string | string[] ; tags?: string | string[] } & { type: "shape" }

Returns

Promise<Shape[]>

get(filter): Promise<StickyNote[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "sticky_note" } & { type?: string | string[] ; tags?: string | string[] } & { type: "sticky_note" }

Returns

Promise<StickyNote[]>

get(filter): Promise<Text[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "text" } & { type?: string | string[] ; tags?: string | string[] } & { type: "text" }

Returns

Promise<Text[]>

get(filter): Promise<Embed[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "embed" } & { type?: string | string[] ; tags?: string | string[] } & { type: "embed" }

Returns

Promise<Embed[]>

get(filter): Promise<Connector[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "connector" } & { type?: string | string[] ; tags?: string | string[] } & { type: "connector" }

Returns

Promise<Connector[]>

get(filter): Promise<Tag[]>

Parameters

NameType
filter{ id: string | string[] } & { type: "tag" } & { type?: string | string[] ; tags?: string | string[] } & { type: "tag" }

Returns

Promise<Tag[]>

get(filter?): Promise<BoardNode[]>

Parameters

NameType
filter?GetFilter

Returns

Promise<BoardNode[]>


getInfo

getInfo(): Promise<BoardInfo>

Fetches basic metadata about the current board:

  • id: unique board ID.
  • createdAt: the date and time when the board was created.
  • updatedAt: the date and time when the board was last modified.

The method takes no arguments.

Example:

const boardInfo = await miro.board.getInfo();

console.log(boardInfo); // => {id: "o9J_g9mOJpo=",createdAt: "2021-06-22T12:33:36.765Z",updatedAt: "2021-08-04T12:57:19.083Z"}

Returns

Promise<BoardInfo>


getUserInfo

getUserInfo(): Promise<UserInfo>

Fetches basic metadata about the currently active user:

  • id: unique user ID.

The method takes no arguments.

Example:

const userInfo = await miro.board.getUserInfo();

console.log(userInfo.id); // => "3658432978520043388"

Returns

Promise<UserInfo>


getSelection

getSelection(): Promise<Item[]>

Fetches the selected items from the board, and it returns them in an array.
If no items are selected on the board, the method returns an empty array.

Example:

// Get an array with the selected item(s) and their properties
const selection = await miro.board.getSelection();

console.log(selection);

Returns

Promise<Item[]>


getAppData

getAppData(): Promise<AppData>

Fetches app metadata stored per board for the specified key.
The appData object can store up to 6 KB of data per board, for all apps combined that use app metadata.
App metadata isn't shared across apps on a board: each app can access only its own metadata.

ℹ️ Note:

  • getAppData returns a new object, not a reference to the object that was previously set with setAppData.
  • If the specified key isn't found, the method throws an error.

Example:

// Add app data to a board
await miro.board.setAppData('activeTags', ['v1', 'v2', 'v3']);

// Get data for key "activeTags" for the app from the board
const activeTags = await miro.board.getAppData('activeTags');

console.log(activeTags); // => ['v1', 'v2', 'v3']

Returns

Promise<AppData>

getAppData<T>(key): Promise<T>

Type parameters

NameType
Textends AppDataValue

Parameters

NameType
keystring

Returns

Promise<T>


setAppData

setAppData<T>(key, value): Promise<T>

Adds app metadata to make it available on the board that the app is running on.
For each board, app metadata is stored per app, and it's available to all the users who can:

  • Access and view the board that the app is running on, AND
  • Run the app on the board.

appData is a key/value pair object. It can contain values with the following data types:

  • string
  • number
  • boolean
  • Object
  • Array

ℹ️ Note:

  • The appData object can store up to 6 KB of data per board, for all apps combined that use app metadata.
    App metadata isn't shared across apps on a board: each app can access only its own metadata.
  • App metadata doesn't expire.
  • You can overwrite the value of an existing key inside appData: if you pass the same key multiple times with different values, only the last/most recent value is stored with the key.
  • After setting a key, you cannot delete it; you can only update it.
    However, you can delete the corresponding value by setting it to null, or to an empty value ('').
  • You can assign an empty array ([]) as the value of a key. It's returned as an empty array.
  • To access app metadata, apps require the boards:read permission.
  • To use the setAppData() method, apps need the boards:write permission.

Example:

// Set app metadata for an imaginary character, and store it for the app at board level.
await miro.board.setAppData('characterCard', {
  name: 'null',
  age: 1,
  good: false,
  alias: ['xenomorph', 'bug', 'crab', 'facehugger', 'alien'],
  abilities: [
    {
      name: 'Acid blood',
      description: 'Can melt through metal.',
    },
    {
      name: 'Regeneration',
      description: 'Can regenerate from a single cell.',
    },
    {
      name: 'Strength',
      description: 'Can lift 20 times its own weight.',
    },
  ],
});

// Get the app metadata about the imaginary character from the board
const characterCard = await miro.board.getAppData('characterCard');

// Clear the metadata about the imaginary character by assigning 'characterCard' an empty object.
await miro.board.setAppData('characterCard', {});

Type parameters

NameType
Textends AppData

Parameters

NameType
keystring
valueAppDataValue

Returns

Promise<T>


getIdToken

getIdToken(): Promise<string>

Retrieves a JSON Web Token (JWT), an encoded form of JSON data, signed with the app client secret.
The JWT that the Web SDK method returns isn't the same type of token as the app access token for the REST API.
Pass the JWT that getIdToken returns as a bearer token to establish communication between the frontend and the backend of a Miro app built on top of the Miro Web SDK.
The token authenticates the app frontend with the app backend. The frontend runs on the board; the backend runs on the server that hosts the app to make it available.


Figure 1. The Web SDK token authenticates app instances running in the frontend with the app backend running on a server.

Example of the decoded JWT structure:

# JWT header
{
  "typ": "JWT", # Token type : JWT
  "alg": "HS256" # Encoding algorithm: HS256
}

# JWT payload
{
  "sub": "3458764521234567890", # Subject: the Client ID of the app that the JWT is issued for
  "iss": "miro", # Issuer: the JWT issuer is Miro
  "team": "3074457350123456789", # ID of the Miro team that the JWT is assigned to
  "exp": 1650619757, # Expiry date of the JWT in Unix epoch time: 1 hour after 'iat'
  "user": "3074457359876543210", # ID of the Miro user that the JWT is assigned to
  "iat": 1650616157 # Issue date of the JWT in Unix epoch time
}

# JWT signature
Signature: RqwL4X4iopF2GH0erQ3cTY_9QWasd5zxUIOPzKLfghj

To authenticate requests from the frontend to the backend of your Miro app:

  • Pass a valid JWT with each request.
  • In the request, include the JWT in the Authorization HTTP header as a Bearer token.

Example:

// Get the JWT signed with your app client secret.
const token = await miro.board.getIdToken();

// Pass the JWT with each request from your app to your backend services.
const response = await fetch('/your-app-server-endpoint', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  };

  body: JSON.stringify(data); // Request body with data payload
});

See also:

Returns

Promise<string>