Miro Performance Tuning

Overview

Optimize Miro REST API v2 throughput and latency. Key levers: minimize API calls with cursor pagination, cache board/item data, batch writes with controlled concurrency, and use connection pooling.

Latency Benchmarks

Typical latencies for api.miro.com (US region):

Cursor Pagination (Eliminate Over-Fetching)

Miro v2 uses cursor-based pagination. Fetch only what you need.

// Efficient paginated iterator
async function* paginateItems(
  boardId: string,
  options: { type?: string; limit?: number } = {}
): AsyncGenerator<MiroBoardItem> {
  const limit = options.limit ?? 50;  // Max 50 per page
  let cursor: string | undefined;

  do {
    const params = new URLSearchParams({ limit: String(limit) });
    if (options.type) params.set('type', options.type);
    if (cursor) params.set('cursor', cursor);

    const response = await fetch(
      `https://api.miro.com/v2/boards/${boardId}/items?${params}`,
      { headers: { 'Authorization': `Bearer ${token}` } }
    );

    const page = await response.json();
    for (const item of page.data) {
      yield item;
    }

    cursor = page.cursor;  // undefined when no more pages
  } while (cursor);
}

// Usage: process items without loading entire board into memory
for await (const item of paginateItems(boardId, { type: 'sticky_note' })) {
  await processItem(item);
}

Caching Strategy

In-Memory Cache (Single Instance)

import { LRUCache } from 'lru-cache';

const boardCache = new LRUCache<string, unknown>({
  max: 500,                    // Max 500 cached entries
  ttl: 60_000,                 // 1 minute TTL
  updateAgeOnGet: true,        // Extend TTL on access
  updateAgeOnHas: false,
});

async function getCachedBoard(boardId: string): Promise<MiroBoard> {
  const cacheKey = `board:${boardId}`;
  const cached = boardCache

Miro Production Checklist

Overview

Complete checklist for deploying Miro REST API v2 integrations to production, covering OAuth configuration, rate limit readiness, monitoring, and rollback.

Pre-Deployment: OAuth & Scopes

• [ ] Production Miro app created at https://developers.miro.com (separate from dev app)
• [ ] OAuth scopes minimized — only scopes actively used (see miro-security-basics)
• [ ] Redirect URI points to production HTTPS endpoint
• [ ] Client secret stored in secret manager (not env vars on disk)
• [ ] Token refresh logic tested — handles expired tokens gracefully
• [ ] Token storage uses encrypted database or vault (not filesystem)

Pre-Deployment: Code Quality

• [ ] No hardcoded tokens — scan with grep -r "eyJ\|Bearer " src/
• [ ] Error handling covers all Miro HTTP status codes (400, 401, 403, 404, 429, 5xx)
• [ ] Rate limiting — backoff with Retry-After header support (see miro-rate-limits)
• [ ] Webhook signatures validated with timing-safe comparison
• [ ] Pagination handled for all list endpoints (cursor parameter)
• [ ] Content-Type header set to application/json on all POST/PATCH requests
• [ ] All tests passing including integration tests against test board

Pre-Deployment: Infrastructure

• [ ] Health check endpoint verifies Miro API connectivity

// GET /health
async function healthCheck() {
  const start = Date.now();
  try {
    const response = await fetch('https://api.miro.com/v2/boards?limit=1', {
      headers: { 'Authorization': `Bearer ${token}` },
      signal: AbortSignal.timeout(5000),
    });

    return {
      miro: {
        status: response.ok ? 'healthy' : 'degraded',
        latencyMs: Date.now() - start,
        rateLimitRemaining: response.headers.get('X-RateLimit-Remaining'),
      },
    };
  } catch (error) {
    return {
      miro: { status: 'unhealthy', latencyMs: Date.now() - start, error: error.message },
    };
  }
}

• [ ] Circuit breaker configured for Miro API calls

class MiroCircuitBreaker {
  private failures = 0;
  private lastFailure = 0;
  private readonly threshold = 5;
  private readonly resetMs = 60000;

  async execute<T>(operation: () => Promise<T>): Promise<T> {
    if (this.isOpen()) {
      throw new Error('Miro circuit breaker is open — API calls suspended');
    }

    try {
      const result = 

Miro Rate Limits

Overview

Miro measures API usage in credits, not raw request counts. Each endpoint consumes a different number of credits based on complexity. The global limit is 100,000 credits per minute per app.

Credit System

Rate Limit Levels

Each Miro REST API endpoint is assigned a rate limit level that determines its credit cost:

The exact credit cost per level is subject to change. Monitor via response headers.

Rate Limit Response Headers

Every Miro API response includes these headers:

When rate limited, the response also includes:

Exponential Backoff with Jitter

interface BackoffConfig {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
  jitterMs: number;
}

const DEFAULT_BACKOFF: BackoffConfig = {
  maxRetries: 5,
  baseDelayMs: 1000,
  maxDelayMs: 32000,
  jitterMs: 500,
};

async function withBackoff<T>(
  operation: () => Promise<Response>,
  config = DEFAULT_BACKOFF
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    const response = await operation();

    if (response.ok) {
      return response.json();
    }

    // Only retry on 429 and 5xx
    if (response.status !== 429 && response.status < 500) {
      const error = await response.json().catch(() => ({}));
      throw new Error(`Miro API ${response.status}: ${error.message ?? 'Request failed'}`);
    }

    if (attempt === config.maxRetries) {
      throw new Error(`Miro API: Max retries (${config.maxRetries}) exceeded`);
    }

    // Prefer Retry-After header if available
    const retryAfter = response.headers.g

Miro Reference Architecture

Overview

Production-ready architecture for Miro REST API v2 integrations. Layered design with a board service, item factory, webhook event processor, and caching layer.

Architecture Diagram

┌──────────────────────────────────────────────────────────┐
│                    API / UI Layer                         │
│   Express routes, Next.js API routes, CLI commands       │
├──────────────────────────────────────────────────────────┤
│                   Service Layer                          │
│   BoardService, ItemService, SyncService                 │
│   (business logic, orchestration, validation)            │
├──────────────────────────────────────────────────────────┤
│                  Miro Client Layer                        │
│   MiroApiClient (REST v2), TokenManager (OAuth 2.0)      │
│   ItemFactory (typed creation), ConnectorBuilder          │
├──────────────────────────────────────────────────────────┤
│                Infrastructure Layer                       │
│   Cache (LRU/Redis), Queue (PQueue), Monitor (metrics)   │
│   WebhookProcessor (signature + idempotency)             │
└──────────────────────────────────────────────────────────┘
                         │
                         ▼
            https://api.miro.com/v2/

Project Structure

src/
├── miro/
│   ├── client.ts              # MiroApiClient — wraps fetch with auth, retries, monitoring
│   ├── token-manager.ts       # OAuth 2.0 token lifecycle (refresh, storage)
│   ├── item-factory.ts        # Typed item creation (sticky notes, shapes, cards, etc.)
│   ├── connector-builder.ts   # Fluent API for creating connectors
│   ├── types.ts               # TypeScript types for all Miro v2 responses
│   └── errors.ts              # MiroApiError, MiroAuthError, MiroRateLimitError
├── services/
│   ├── board-service.ts       # Board CRUD + member management
│   ├── item-service.ts        # Item CRUD + tag operations
│   ├── sync-service.ts        # Two-way sync between Miro and your database
│   └── search-service.ts      # Find items by content, type, or tag
├── webhooks/
│   ├── handler.ts             # Express/serverless webhook endpoint
│   ├── processor.ts           # Event routing and processing
│   └── idempotency.ts         # Duplicate event prevention
├── cache/
│   ├── board-cache.ts         # Board metadata cache
│   └── item-cache.ts          # Item data cache with webhook invalidation
├── config/
│   ├── miro.ts                # Environment-based Miro configuration
│   └── index.ts               # Config loader
└── monitoring/
    ├── metrics.ts             # Prometheus counters/histograms for Miro API
    └── health.ts              # Health check endpoint

Core Components

MiroApiClient

// src/miro/client.ts
export class MiroApiClient {
  constructor(
    private tokenManager: TokenManager,
    

Miro SDK Patterns

Overview

Production-ready patterns for the @mirohq/miro-api Node.js client and direct REST API v2 usage. Covers the high-level Miro client (stateful, OAuth-aware) and the low-level MiroApi client (stateless, token-based).

Prerequisites

• @mirohq/miro-api installed
• TypeScript 5+ project
• Understanding of Miro REST API v2 item model

Two Client Modes

import { Miro, MiroApi } from '@mirohq/miro-api';

// HIGH-LEVEL: Stateful, manages OAuth tokens per user
// Use for multi-user apps (SaaS, web apps with OAuth)
const miro = new Miro({
  clientId: process.env.MIRO_CLIENT_ID!,
  clientSecret: process.env.MIRO_CLIENT_SECRET!,
  redirectUrl: process.env.MIRO_REDIRECT_URI!,
});
const userApi = await miro.as('user-id');  // Returns MiroApi scoped to user

// LOW-LEVEL: Stateless, pass token directly
// Use for scripts, automation, single-user integrations
const api = new MiroApi(process.env.MIRO_ACCESS_TOKEN!);

Pattern 1: Type-Safe Board Service

// src/miro/board-service.ts
import { MiroApi } from '@mirohq/miro-api';

// Response types matching Miro REST API v2
interface MiroBoard {
  id: string;
  type: 'board';
  name: string;
  description: string;
  createdAt: string;
  modifiedAt: string;
}

interface MiroBoardItem {
  id: string;
  type: 'sticky_note' | 'shape' | 'card' | 'text' | 'frame' | 'image' | 'document' | 'embed' | 'app_card';
  data: Record<string, unknown>;
  position: { x: number; y: number; origin: string };
  geometry?: { width?: number; height?: number };
  createdAt: string;
  createdBy: { id: string; type: string };
}

interface PaginatedResponse<T> {
  data: T[];
  total: number;
  size: number;
  offset: number;
  limit: number;
  cursor?: string;
}

export class BoardService {
  constructor(private api: MiroApi) {}

  async getBoard(boardId: string): Promise<MiroBoard> {
    const response = await this.api.getBoard(boardId);
    return response.body as unknown as MiroBoard;
  }

  async listItems(
    boardId: string,
    options: { type?: string; limit?: number; cursor?: string } = {}
  ): Promise<PaginatedResponse<MiroBoardItem>> {
    const params = new URLSearchParams();
    if (options.type) params.set('type', options.type);
    if (options.limit) params.set('limit', String(options.limit));
    if (options.cursor) params.set('cursor', options.cursor);

    const response = await fetch(
      `https://api.miro.com/v2/boards/${boardId}/items?${params}`,
      { headers: this.authHeaders() }
    );
    return response.json();
  }

  async getAllItems(boardId: string): Promise<MiroBoardItem[]> {
    const items: MiroBoardItem[] = [];
 

Miro Security Basics

Overview

Security best practices for Miro OAuth 2.0 tokens, webhook signatures, and access control across the REST API v2.

Prerequisites

• Miro app created at https://developers.miro.com
• Understanding of OAuth 2.0 concepts
• Secret management solution for production

OAuth Token Security

Never Store Tokens in Code

# .env (NEVER commit to git)
MIRO_CLIENT_ID=3458764500000001
MIRO_CLIENT_SECRET=your_client_secret_here
MIRO_ACCESS_TOKEN=eyJ...
MIRO_REFRESH_TOKEN=eyJ...

# .gitignore — MUST include these
.env
.env.local
.env.*.local
*.pem

Scope Minimization

Request only the scopes your app actually needs. Fewer scopes = smaller blast radius if a token is compromised.

Token Lifecycle Management

// src/miro/token-manager.ts

interface TokenInfo {
  accessToken: string;
  refreshToken: string;
  expiresAt: number;  // Unix timestamp in ms
  scopes: string[];
}

class MiroTokenManager {
  constructor(
    private storage: TokenStorage,   // DB, Redis, or Vault
    private clientId: string,
    private clientSecret: string,
  ) {}

  async getValidToken(userId: string): Promise<string> {
    const info = await this.storage.get(userId);
    if (!info) throw new Error('User not authorized');

    // Refresh 5 minutes before expiry
    if (Date.now() > info.expiresAt - 300_000) {
      return this.refreshToken(userId, info.refreshToken);
    }

    return info.accessToken;
  }

  private async refreshToken(userId: string, refreshToken: string): Promise<string> {
    const response = await fetch('https://api.miro.com/v1/oauth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        client_id: this.clientId,
        client_secret: this.clientSecret,
        refresh_token: refreshToken,
      }),
    });

    if (!response.ok) {
      // Refresh token revoked or expired — user must re-authorize
      await this.storage.delete(userId);
      throw new Error('Miro refresh token invalid. User must re-authorize.');
    }

    cons

Miro Upgrade & Migration

Overview

Guide for migrating from Miro REST API v1 to v2, upgrading the @mirohq/miro-api SDK, and handling the key breaking changes between versions.

Key Breaking Changes: v1 to v2

Terminology Changes

Endpoint Migration Map

# v1 (DEPRECATED)                          → v2 (CURRENT)
POST /v1/boards/{id}/widgets               → POST /v2/boards/{id}/sticky_notes
                                              POST /v2/boards/{id}/shapes
                                              POST /v2/boards/{id}/cards
                                              POST /v2/boards/{id}/texts
                                              POST /v2/boards/{id}/frames
                                              POST /v2/boards/{id}/images
                                              POST /v2/boards/{id}/documents
                                              POST /v2/boards/{id}/embeds
                                              POST /v2/boards/{id}/app_cards

GET  /v1/boards/{id}/widgets               → GET  /v2/boards/{id}/items
GET  /v1/boards/{id}/widgets/{widget_id}   → GET  /v2/boards/{id}/items/{item_id}
                                              (or type-specific: /v2/boards/{id}/sticky_notes/{item_id})

POST /v1/boards/{id}/widgets (type: line)  → POST /v2/boards/{id}/connectors
GET  /v1/boards/{id}/widgets?type=line     → GET  /v2/boards/{id}/connectors

Request Body Changes

// v1: Create a sticky note (via universal widgets endpoint)
// POST /v1/boards/{id}/widgets
{
  "type": "sticker",
  "text": "Hello World",
  "style": {
    "stickerBackgroundColor": "#FFFF00"
  },
  "x": 100,
  "y": 200,
  "width": 200
}

// v2: Create a sticky note (dedicated endpoint)
// POST /v2/boards/{id}/sticky_notes
{
  "data": {
    &quo

Miro Webhooks & Events

Overview

Receive real-time notifications when items on a Miro board change. Miro uses board subscriptions via the /v2-experimental/webhooks/board_subscriptions endpoint. All board item types are supported except tags, connectors, and comments.

Prerequisites

• Access token with boards:read scope
• HTTPS endpoint accessible from the internet
• Webhook signing secret (generated when creating subscription)

Create a Board Subscription

// POST https://api.miro.com/v2-experimental/webhooks/board_subscriptions
async function createBoardSubscription(boardId: string, callbackUrl: string) {
  const response = await fetch(
    'https://api.miro.com/v2-experimental/webhooks/board_subscriptions',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.MIRO_ACCESS_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        boardId,
        callbackUrl,       // Must be HTTPS
        status: 'enabled', // 'enabled' | 'disabled'
      }),
    }
  );

  const subscription = await response.json();
  console.log(`Subscription created: ${subscription.id}`);
  console.log(`Type: ${subscription.type}`);  // 'board_subscription'
  return subscription;
}

Manage Subscriptions

// List subscriptions
// GET https://api.miro.com/v2-experimental/webhooks/board_subscriptions
const list = await miroFetch('/v2-experimental/webhooks/board_subscriptions');

// Get a specific subscription
// GET https://api.miro.com/v2-experimental/webhooks/board_subscriptions/{subscription_id}
const sub = await miroFetch(`/v2-experimental/webhooks/board_subscriptions/${subId}`);

// Update subscription (enable/disable)
// PATCH https://api.miro.com/v2-experimental/webhooks/board_subscriptions/{subscription_id}
await miroFetch(`/v2-experimental/webhooks/board_subscriptions/${subId}`, 'PATCH', {
  status: 'disabled',
});

// Delete subscription
// DELETE https://api.miro.com/v2-experimental/webhooks/board_subscriptions/{subscription_id}
await miroFetch(`/v2-experimental/webhooks/board_subscriptions/${subId}`, 'DELETE');

Event Payload Structure

When a board item is created, updated, or deleted, Miro sends a POST request to your callback URL:

{
  "event": "board_subscription_changed",
  "type": "update",
  "boardId": "uXjVN1234567890",
  "item": {
    "id": "3458764500000001",
    "type": "sticky_note"
  },
  "changes": [
    {
      "property": "data.content",
      "previousValue": "Ol