Miro Multi-Environment Setup
Overview
Configure separate Miro app credentials, OAuth scopes, and board access for development, staging, and production. Miro does not provide a sandbox API; all environments use https://api.miro.com/v2/ — isolation is achieved through separate apps and dedicated boards.
Environment Strategy
| Environment | Miro App | Boards | Scopes | Token Storage |
|---|
| Development | MyApp (Dev) | 1 dedicated test board | boards:read, boards:write | .env.local |
| Staging | MyApp (Staging) | Staging workspace boards | All required scopes | Secret Manager |
| Production | MyApp (Production) | Production boards | Minimum required scopes | Secret Manager + rotation |
Key insight: Create a separate Miro app at https://developers.miro.com for each environment. This gives you independent client IDs, secrets, and OAuth redirect URIs.
Configuration Structure
config/
├── miro.base.ts # Shared settings (timeouts, retry policy)
├── miro.development.ts # Dev overrides
├── miro.staging.ts # Staging overrides
└── miro.production.ts # Prod overrides
Base Configuration
export const miroBaseConfig = {
apiBase: 'https://api.miro.com/v2',
tokenEndpoint: 'https://api.miro.com/v1/oauth/token',
timeout: 30000,
retries: 3,
backoff: { baseMs: 1000, maxMs: 32000, jitterMs: 500 },
cache: { ttlSeconds: 120 },
rateLimit: { maxConcurrency: 5, requestsPerSecond: 10 },
};
Environment Configs
import { miroBaseConfig } from './miro.base';
export const miroDevConfig = {
...miroBaseConfig,
clientId: process.env.MIRO_CLIENT_ID!,
clientSecret: process.env.MIRO_CLIENT_SECRET!,
redirectUri: 'http://localhost:3000/auth/miro/callback',
testBoardId: process.env.MIRO_TEST_BOARD_ID,
cache: { ttlSeconds: 10 },
logLevel: 'debug',
};
export const miroStagingConfig = {
...miroBaseConfig,
clientId: process.env.MIRO_CLIENT_ID_STAGING!,
clientSecret: process.env.MIRO_CLIENT_SECRET_STAGING!,
redirectUri: 'https://staging.myapp.com/auth/miro/callback',
cache: { ttlSeconds: 60 },
logLevel: 'info',
};
export const miroProdConfig = {
...miroBaseConfig,
clientId: process.env.MIRO_CLIENT_ID_PROD!,
clientSecret: process.env.!,
: ,
: ,
: { : },
: ,
};
Config Loader
type Environment = 'development' | 'staging' | 'production';
export function loadMiroConfig() {
const env = (process.env.NODE_ENV ?? 'development') as Environment;
switch (env) {
case 'production': return miroProdConfig;
case 'staging': return miroStagingConfig;
default: return miroDevConfig;
}
}
Secret Management
Development: .env.local
MIRO_CLIENT_ID=3458764500000001
MIRO_CLIENT_SECRET=dev_secret_here
MIRO_ACCESS_TOKEN=dev_access_token
MIRO_REFRESH_TOKEN=dev_refresh_token
MIRO_TEST_BOARD_ID=uXjVN_dev_board
MIRO_WEBHOOK_SECRET=dev_webhook_secret
Staging/Production: Secret Manager
gcloud secrets create miro-client-secret-staging --data-file=<(echo -n "staging_secret")
gcloud secrets create miro-client-secret-prod --data-file=<(echo -n "prod_secret")
aws secretsmanager create-secret \
--name miro/staging/client-secret \
--secret-string "staging_secret"
aws secretsmanager create-secret \
--name miro/production/client-secret \
--secret-string "prod_secret"
vault kv put secret/miro/staging client_secret=staging_secret
vault kv put secret/miro/production client_secret=prod_secret
CI/CD Secrets (GitHub Actions)
gh secret set MIRO_CLIENT_ID_DEV --body "dev_client_id"
gh secret set MIRO_CLIENT_SECRET_DEV --body "dev_client_secret"
gh secret set MIRO_CLIENT_ID_STAGING --body "staging_client_id"
gh secret set MIRO_CLIENT_SECRET_STAGING --body "staging_client_secret"
gh secret set MIRO_CLIENT_ID_PROD --body "prod_client_id"
gh secret set MIRO_CLIENT_SECRET_PROD --body "prod_client_secret"
Environment Guards
Prevent production-dangerous operations in development:
const config = loadMiroConfig();
function guardProduction(operation: string): void {
if (config.environment === 'development') {
throw new Error(`${operation} blocked in development — use staging or production`);
}
}
function guardDestructive(operation: string, boardId: string): void {
const protectedBoards = process.env.MIRO_PROTECTED_BOARDS?.split(',') ?? [];
if (protectedBoards.includes(boardId)) {
throw new Error(`${operation} blocked on protected board ${boardId}`);
}
}
async function deleteBoard(boardId: string): Promise<void> {
guardDestructive('deleteBoard', boardId);
await api.fetch(`/v2/boards/`, );
}
OAuth Redirect URI per Environment
Each Miro app must have its redirect URI configured to match the environment:
| Environment | Redirect URI | Where to Configure |
|---|
| Development | http://localhost:3000/auth/miro/callback | Miro app "Dev" settings |
| Staging | https://staging.myapp.com/auth/miro/callback | Miro app "Staging" settings |
| Production | https://myapp.com/auth/miro/callback | Miro app "Production" settings |
Miro requires exact redirect URI match. No wildcards.
Board Isolation Strategy
async function cleanupDevBoard(): Promise<void> {
const testBoardId = config.testBoardId;
if (!testBoardId) return;
const items = await api.fetchAll(`/v2/boards/${testBoardId}/items`);
for (const item of items) {
await api.fetch(`/v2/boards/${testBoardId}/items/${item.id}`, 'DELETE');
}
console.log(`Cleaned ${items.length} items from dev board`);
}
Error Handling
| Issue | Cause | Solution |
|---|
| Wrong redirect URI | Env mismatch | Check Miro app settings for this environment |
| Staging token on prod board | Mixed credentials | Use separate Miro apps per env |
| Secret not found | Wrong secret path | Verify secret manager key for this env |
| Dev board full | No cleanup between runs | Run cleanupDevBoard() in test teardown |
Resources
Next Steps
For observability setup, see miro-observability.
