Miro Prod Checklist

Miro Production Checklist

Overview

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

Prerequisites

Before applying this guide, confirm you have a Miro app or workspace appropriate to the task, a dedicated non-production board where changes can be tested safely, and only the OAuth scopes or administrative access the procedure requires.

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 = await operation();
      this.failures = 0;
      return result;
    } catch (error) {
      this.failures++;
      this.lastFailure = Date.now();
      throw error;
    }
  }

  private isOpen(): boolean {
    if (this.failures < this.threshold) return false;
    if (Date.now() - this.lastFailure > this.resetMs) {
      this.failures = 0; // Half-open: allow one retry
      return false;
    }
    return true;
  }
}

• Graceful degradation — app continues working if Miro API is unavailable
• Monitoring — Prometheus/Datadog metrics for Miro API latency and error rates
• Alerting configured for error rate >5%, P95 latency >3s, and 429 responses

Pre-Deployment: Miro App Settings

• App name and description are professional (visible to users during OAuth consent)
• App icon uploaded (displayed in Miro marketplace and OAuth screen)
• Support email configured in app settings
• App manifest reviewed if using Miro app manifest format

Deployment Verification

Instructions

Complete the checklist in deployment order: confirm the production OAuth configuration and code safeguards, deploy with monitoring enabled, then run the verification commands. If a verification fails, use the rollback procedure before enabling additional traffic.

Output

The checklist produces documented launch evidence: successful OAuth and health checks, observed rate-limit headroom, monitoring coverage, and either a confirmed rollout or a recorded rollback decision.

Examples

Run the deployment verification commands against the production endpoint only after the non-production integration suite has passed. A healthy result includes an HTTP success response and a readable health payload with Miro status information.

# 1. Verify production token works
curl -s -w "\nHTTP %{http_code} in %{time_total}s\n" \
  -H "Authorization: Bearer $MIRO_ACCESS_TOKEN_PROD" \
  "https://api.miro.com/v2/boards?limit=1"

# 2. Check rate limit headroom
curl -sI -H "Authorization: Bearer $MIRO_ACCESS_TOKEN_PROD" \
  "https://api.miro.com/v2/boards?limit=1" | grep -i ratelimit

# 3. Verify webhook endpoint is reachable (if using webhooks)
curl -s -o /dev/null -w "%{http_code}" https://your-app.com/webhooks/miro

# 4. Verify health check
curl -s https://your-app.com/health | jq '.miro'

Post-Deployment Monitoring

Rollback Procedure

# Immediate rollback — disable Miro integration
# Option 1: Feature flag
curl -X PATCH https://config.your-app.com/flags \
  -d '{"miro_enabled": false}'

# Option 2: Environment variable
# Set MIRO_ENABLED=false and restart

# Option 3: Container rollback
kubectl rollout undo deployment/miro-integration
kubectl rollout status deployment/miro-integration

Documentation Requirements

• Incident runbook created (see miro-incident-runbook)
• Token rotation procedure documented
• On-call escalation path includes Miro-specific steps
• Board cleanup procedure for orphaned test data

Error Handling

For authentication, rate-limit, or availability failures during deployment, keep the integration disabled or roll it back, capture sanitized evidence, and use the incident runbook. Do not retry a rollout until the failed prerequisite or verification check has a documented resolution.

Resources

• Miro App Settings
• Miro Status Page
• App Manifest

Next Steps

For version upgrades, see miro-upgrade-migration.