How to Integrate Bolt.new with Miro

Miro REST API access requires a registered Miro app. Navigate to miro.com/app-install (or Miro's developer portal at developers.miro.com) and click 'Create new app'. Give your app a name like 'Bolt Integration' and select the team you want it to have access to. You will see your app's Client ID and Client Secret on the app configuration page. For single-user server-side integrations, you do not need to implement the full OAuth 2.0 flow. Instead, generate a static access token: in your app's settings page, scroll to the 'Access token' section and click 'Create access token'. Select the scopes your integration needs: boards:read to fetch board items, boards:write to create and update items. Copy the generated token — this is a long-lived token that authenticates your API requests. Your board ID is the alphanumeric string at the end of the board URL. When you have a Miro board open, the URL looks like: miro.com/app/board/uXjVPxxxxxxxxx=/ — the board ID is uXjVPxxxxxxxxx=. Note that board IDs include the trailing equals signs if present. For embedding boards without the REST API, no token is needed at all. The Miro embed URL format is: https://miro.com/app/board/{boardId}/?moveToViewport=&embedMode=view. Any board set to 'Anyone with the link can view' can be embedded without authentication. For private boards, the viewer needs a Miro account and appropriate board access. Store your access token in .env.local as MIRO_ACCESS_TOKEN. Board IDs are public identifiers and can be stored as NEXT_PUBLIC_MIRO_BOARD_ID if needed in client-side components, though for consistency keep all Miro configuration server-side.

1// .env.local
2MIRO_ACCESS_TOKEN=your_miro_app_access_token
3MIRO_BOARD_ID=your_board_id_from_url

The simplest Miro integration is embedding a board directly in your Bolt app as an iframe. This requires no API calls and works immediately in Bolt's WebContainer preview — no deployment needed. Create a React component that renders the Miro board in a sized container. Miro's embed URL format: https://miro.com/app/live-embed/{boardId}/ for live collaborative embeds, or https://miro.com/app/board/{boardId}/?embedMode=view for view-only mode. The live embed allows full interaction — editing sticky notes, creating items, collaborating in real time — while view-only shows the board read-only. For more advanced control over the embedded board, add the Miro Web SDK. The SDK allows JavaScript communication with the embedded board: getting the current viewport, selecting items, or responding to cursor position changes. Add the SDK via script tag: https://miro.com/app/static/sdk/v2/miro.js. Note that OAuth flows and social login features fail in Miro's embedded board when viewed inside an iFrame in Bolt's WebContainer during development. The WebContainer enforces strict iframe isolation headers. This is only relevant if your Miro board requires authentication from viewers — for boards shared with 'anyone with the link', the embed works without authentication. The authentication limitation applies only in the Bolt development preview, not in production. For production use, embedded Miro boards require that the viewer either has a Miro account with board access or that the board is publicly shared. Plan your access settings accordingly before embedding.

1// components/MiroBoardEmbed.tsx
2'use client';
3
4import { useState } from 'react';
5
6type MiroBoardEmbedProps = {
7  boardId: string;
8  mode?: 'live' | 'view';
9  height?: number;
10};
11
12export function MiroBoardEmbed({ boardId, mode = 'live', height = 600 }: MiroBoardEmbedProps) {
13  const [hasError, setHasError] = useState(false);
14
15  const embedUrl =
16    mode === 'live'
17      ? `https://miro.com/app/live-embed/${boardId}/`
18      : `https://miro.com/app/board/${boardId}/?embedMode=view`;
19
20  const boardUrl = `https://miro.com/app/board/${boardId}/`;
21
22  if (hasError) {
23    return (
24      <div className="flex flex-col items-center justify-center p-8 border rounded-lg bg-gray-50">
25        <p className="text-gray-600 mb-3">Board could not be loaded in embedded view.</p>
26        <a
27          href={boardUrl}
28          target="_blank"
29          rel="noopener noreferrer"
30          className="text-blue-600 underline"
31        >
32          Open board in Miro
33        </a>
34      </div>
35    );
36  }
37
38  return (
39    <div className="w-full">
40      <iframe
41        src={embedUrl}
42        width="100%"
43        height={height}
44        frameBorder="0"
45        scrolling="no"
46        allowFullScreen
47        onError={() => setHasError(true)}
48        title="Miro Board"
49        className="rounded-lg border border-gray-200"
50      />
51      <div className="mt-2 text-right">
52        <a
53          href={boardUrl}
54          target="_blank"
55          rel="noopener noreferrer"
56          className="text-sm text-gray-500 hover:text-gray-700"
57        >
58          Open in Miro →
59        </a>
60      </div>
61    </div>
62  );
63}

Miro's REST API v2 provides full CRUD access to board items. The main endpoints you need: GET /v2/boards/{boardId}/items returns all items on a board (sticky notes, text, shapes, frames, connectors, images, cards). You can filter by type using the type query parameter — e.g., ?type=sticky_note returns only sticky notes. Sticky note items have: id, type ('sticky_note'), data.content (the text), style.fillColor (background color), position (x, y coordinates), geometry (width, height). Shape items have: type ('shape'), data.shape (the shape type like 'rectangle', 'circle'), data.content (text inside the shape), style.fillColor, style.borderColor, and position/geometry. To create a sticky note, POST to /v2/boards/{boardId}/sticky_notes with the item data. The create request requires at minimum a data object with content. Optional: style (fillColor, textAlign), position (x, y coordinates on the board canvas — Miro uses a large coordinate space, typical values range in the thousands), and geometry (width, height in pixels). Colors are CSS color names like 'yellow', 'blue', 'green', 'orange', 'red', 'violet', 'pink', 'dark_green', 'dark_blue', 'dark_red', 'dark_violet', 'dark_yellow', 'gray', 'dark_gray'. Creating shapes follows the same pattern using POST /v2/boards/{boardId}/shapes. Frames (containers for grouping items) use POST /v2/boards/{boardId}/frames. Creating frames with a title gives you named sections on the board, useful for organizing auto-generated content. All these REST API calls are outbound HTTP requests from your Next.js API route, which work perfectly in Bolt's WebContainer without deploying.

1// app/api/miro/sticky-notes/create/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const MIRO_API = 'https://api.miro.com/v2';
5const ACCESS_TOKEN = process.env.MIRO_ACCESS_TOKEN;
6const BOARD_ID = process.env.MIRO_BOARD_ID;
7
8const STICKY_COLORS = [
9  'yellow', 'blue', 'green', 'orange', 'red', 'violet',
10  'pink', 'dark_green', 'dark_blue', 'dark_red',
11] as const;
12
13type StickyColor = typeof STICKY_COLORS[number];
14
15export async function POST(request: NextRequest) {
16  const { content, color = 'yellow', x = 0, y = 0 } = await request.json();
17
18  if (!content || typeof content !== 'string' || content.trim() === '') {
19    return NextResponse.json({ error: 'content is required' }, { status: 400 });
20  }
21
22  const validColor: StickyColor = STICKY_COLORS.includes(color as StickyColor)
23    ? (color as StickyColor)
24    : 'yellow';
25
26  const body = {
27    data: { content: content.trim() },
28    style: { fillColor: validColor },
29    position: { x, y, origin: 'center' },
30  };
31
32  const response = await fetch(`${MIRO_API}/boards/${BOARD_ID}/sticky_notes`, {
33    method: 'POST',
34    headers: {
35      Authorization: `Bearer ${ACCESS_TOKEN}`,
36      'Content-Type': 'application/json',
37    },
38    body: JSON.stringify(body),
39  });
40
41  if (!response.ok) {
42    const error = await response.json();
43    return NextResponse.json({ error: error.message ?? 'Miro API error' }, { status: response.status });
44  }
45
46  const item = await response.json();
47  return NextResponse.json({
48    id: item.id,
49    content: item.data.content,
50    color: item.style.fillColor,
51    position: item.position,
52  });
53}

Miro webhooks notify your app when board items change — sticky notes are added or updated, frames are moved, items are deleted. This is useful for apps that stay synchronized with an active Miro board during a workshop or design session. To deploy, click Publish in Bolt's top-right corner for Netlify, or push to GitHub and connect to Vercel. After deployment, add MIRO_ACCESS_TOKEN and MIRO_BOARD_ID to your hosting platform's environment variables. Register a Miro webhook via POST https://api.miro.com/v2/webhooks/board/{boardId} with your access token. The request body includes: callbackUrl (your deployed endpoint URL), status ('enabled' to activate immediately), and boardId. Miro webhooks fire for board_item_created, board_item_updated, and board_item_deleted events. Each webhook payload contains: event (the event type), boardId, item (the affected board item with all its properties), and createdAt (timestamp). For board_item_updated events, the item reflects its current state after the change — Miro does not include a diff of what changed, so if you need to track changes you must store the previous state. Miro does not use a signature verification system for webhooks (unlike Stripe or Asana). Verify that incoming requests are genuinely from Miro by checking the User-Agent header (should be 'miro-webhooks/1.0') and ensuring the boardId in the payload matches your expected board. During development in Bolt's WebContainer, your app has no public URL and cannot receive inbound webhook requests. This is a fundamental constraint of the WebContainer architecture — all incoming network connections are blocked in the browser-based runtime. Deploy to Netlify or Vercel to test webhooks against a real public URL.

1// app/api/miro/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4type MiroWebhookPayload = {
5  event: 'board_item_created' | 'board_item_updated' | 'board_item_deleted';
6  boardId: string;
7  item: {
8    id: string;
9    type: string;
10    data?: { content?: string };
11  };
12  createdAt: string;
13};
14
15export async function POST(request: NextRequest) {
16  // Basic validation: verify the request appears to be from Miro
17  const userAgent = request.headers.get('user-agent') ?? '';
18  if (!userAgent.includes('miro')) {
19    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
20  }
21
22  const payload: MiroWebhookPayload = await request.json();
23  const { event, boardId, item } = payload;
24
25  console.log(`Miro webhook: ${event}`, {
26    boardId,
27    itemId: item.id,
28    itemType: item.type,
29    content: item.data?.content?.slice(0, 100),
30  });
31
32  switch (event) {
33    case 'board_item_created':
34      // Handle new item — trigger sync, send notification, etc.
35      break;
36    case 'board_item_updated':
37      // Handle item change
38      break;
39    case 'board_item_deleted':
40      // Handle deletion
41      break;
42  }
43
44  return NextResponse.json({ received: true });
45}