miro-security-basics

name	miro-security-basics
description	Apply Miro REST API v2 security best practices — OAuth scope minimization, token storage, webhook signature validation, and secret rotation. Trigger with phrases like "miro security", "miro secrets", "secure miro", "miro token security", "miro webhook signature".
allowed-tools	Read, Write, Grep
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","miro","security","oauth"]
compatibility	Designed for Claude Code

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.

Use Case	Minimum Scopes
Read-only dashboard	boards:read
Board automation	boards:read, boards:write
Team management	boards:read, team:read, team:write
Enterprise admin	boards:read, organizations:read, auditlogs:read
Full integration	boards:read, boards:write, identity:read

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);
    }

     info.;
  }

    (: , : ): <> {
     response =  (, {
      : ,
      : { :  },
      :  ({
        : ,
        : .,
        : .,
        : refreshToken,
      }),
    });

     (!response.) {
      
       ..(userId);
        ();
    }

     data =  response.();
     ..(userId, {
      : data.,
      : data.,
      : .() + data. * ,
      : data..(),
    });

     data.;
  }
}

Webhook Signature Validation

Miro signs webhook payloads so you can verify they originate from Miro's servers.

import crypto from 'crypto';

function verifyMiroWebhookSignature(
  rawBody: Buffer | string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  // Timing-safe comparison to prevent timing attacks
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex'),
    );
  } catch {
    return false; // Different lengths = not equal
  }
}

// Express middleware
app.post('/webhooks/miro',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const signature = req.headers['x-miro-signature'] as string;
    if (!signature || !verifyMiroWebhookSignature(req.body, signature, process..!)) {
       res.().({ :  });
    }

     event = .(req..());
    
    res.().({ :  });
  }
);

Client Secret Rotation

# Step 1: Generate new secret in Miro app settings
# https://developers.miro.com > Your apps > Select app > App Credentials

# Step 2: Update secret in your environment
# For production (example with GCP Secret Manager):
gcloud secrets versions add miro-client-secret \
  --data-file=<(echo -n "new_secret_value")

# Step 3: Verify new secret works
curl -X POST https://api.miro.com/v1/oauth/token \
  -d "grant_type=refresh_token" \
  -d "client_id=$MIRO_CLIENT_ID" \
  -d "client_secret=NEW_SECRET" \
  -d "refresh_token=$MIRO_REFRESH_TOKEN"

# Step 4: Revoke old secret in Miro app settings

Request Signing for Audit Trails

interface MiroAuditEntry {
  timestamp: string;
  userId: string;
  endpoint: string;
  method: string;
  boardId?: string;
  requestId?: string;  // From X-Request-Id response header
  status: number;
}

async function auditedMiroFetch(
  userId: string,
  path: string,
  options: RequestInit = {},
): Promise<Response> {
  const response = await fetch(`https://api.miro.com${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${await tokenManager.getValidToken(userId)}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  const audit: MiroAuditEntry = {
    timestamp: new Date().toISOString(),
    userId,
    endpoint: path,
    method: options.method ?? ,
    : path.()?.[],
    : response..() ?? ,
    : response.,
  };

  
  .(, .(audit));

   response;
}

Security Checklist

• Access tokens stored in environment variables or secret manager, never in code
• .env files in .gitignore
• OAuth scopes minimized per environment
• Webhook signatures validated with timing-safe comparison
• Token refresh handled before expiry (5-minute buffer)
• Failed refresh triggers re-authorization flow
• Client secret rotation procedure documented and tested
• Audit logging captures endpoint, method, user, and status (never tokens)
• X-Request-Id captured for support ticket correlation

Instructions

Use the ordered procedures and code samples in this guide as a sequence: begin with the prerequisites, apply the configuration or operational step for the target environment, then perform the documented validation or cleanup before proceeding. Keep credentials in the documented secret store; never hard-code them in source.

Output

Following this guide produces the Miro integration outcome for its topic—configuration, validation evidence, operational recovery, or a documented migration result. Record command output and relevant identifiers so a failed step is traceable.

Examples

Start with the smallest applicable command or code example in the relevant section, using a dedicated test board and non-production credentials. Confirm the expected response or validation result before applying the pattern to production.

Error Handling

Security Issue	Detection	Mitigation
Token in logs	Log audit	Redact Authorization headers in logging middleware
Token in git	Pre-commit hook / secret scanning	Rotate immediately, revoke old token
Webhook forgery	Signature validation fails	Return 401, alert security team
Excessive scopes	Scope audit	Reduce to minimum needed per endpoint

Resources

• Miro OAuth 2.0
• Permission Scopes
• Troubleshoot OAuth 2.0

Next Steps

For production deployment, see miro-prod-checklist.