Master Keys vs Channel Keys — MutoPay Docs

Use channel keys for every integration that only needs to create payments. Reserve the master key for automation that must see or manage the whole account. This is a least-privilege default — each channel key’s blast radius is limited to its own integration.

Comparison

	Channel key	Master key
Prefix	`ep_`	`msk_`
Header	`X-API-Key: ep_...`	`Authorization: Bearer msk_...`
Count per account	Many (one per integration)	One
Create payments	✅	✅
List all payments	Only its own	✅ all
Manage channels	❌	✅
Change settlement token / wallet	❌	✅
Rotate or revoke itself	❌	❌ (dashboard JWT required)
Suspended merchant	403	403

When to use which

WooCommerce, Shopify, mobile apps, SaaS billing hooks → channel key. One per plugin install or app build. Scope of damage if leaked: limited to that one integration.
Back-office reconciliation script, BI sync, CRM integration → master key. Needs to list all payments across every channel.
Ops runbook: rotate settlement wallet for the whole account → master key. (Or use the dashboard.)
Customer-facing code that makes API calls from the browser → never use either. Keep all API keys server-side.

Rotation

Channel key rotation

From Settings → Channels, click Rotate API key on the channel.
The new key is shown once. Update your integration.
The old key is invalid immediately — plan a brief deploy window.

Master key rotation

From Settings → Master API Key, click Rotate. Browser JWT (your Google Sign-In session) is required. A master key cannot rotate itself — deliberate, so a leaked master key cannot lock the legitimate owner out.
The new key is shown once.

What to do if a key leaks

Channel key → rotate it immediately from the channel settings. This invalidates the leaked key. Review payments created during the window to spot unauthorized use.
Master key → log into the dashboard (Google Sign-In) and rotate. Then review all recent activity: GET https://mutopay.com/api/merchant/payments with the new key.