# Master Keys vs Channel Keys

> MutoPay has two kinds of API keys: channel keys for creating payments, master keys for account-wide management. Use the weaker one per integration; reserve the master key for automation that genuinely needs account-wide access.

Source: https://mutopay.com/docs/master-keys-vs-channel-keys/
Language: en

---

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](https://mutopay.com/dashboard/settings), 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](https://mutopay.com/dashboard/settings), click **Rotate**. Browser JWT (your Google Sign-In session) is required. A master key **cannot rotate itself**. This is 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

1. **Channel key** → rotate it immediately from the channel settings. This invalidates the leaked key. Review payments created during the window to spot unauthorized use.
2. **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.

## See also

- [Authentication](/docs/authentication/): full auth reference.
- [Create a Payment](/docs/create-payment/): uses a channel key.