Authentication

MutoPay has three authentication methods — channel API keys for creating payments, master API keys for account management, and JWTs for the browser dashboard. This page explains when to use which.

MutoPay has three authentication methods. Most integrations only need the first two.

CredentialPrefixHeaderUse for
Channel API keyep_X-API-Key: ep_...Creating payments from a specific integration (WooCommerce, mobile app, SaaS billing)
Master API keymsk_Authorization: Bearer msk_...Headless account management — list payments, manage channels, change settlement settings
Browser JWT—Authorization: Bearer <jwt>The dashboard at mutopay.com/dashboard. Issued by Google Sign-In. You will not usually handle these directly.

Channel API keys

One channel per integration. Each channel has its own API key, webhook URL, and webhook secret. Revoke or rotate one integration without affecting the others.

Create a channel at Settings → Channels. The full key is shown once; store it in your secret manager.

Use the channel key on POST /api/payments:

POST /api/payments HTTP/1.1
Host: mutopay.com
X-API-Key: ep_live_4b8f...
Content-Type: application/json

{"amount_usd": 25.00, "description": "Order #1042"}

A channel key cannot:

  • List or read other channels’ payments
  • Rotate itself
  • Change account settings

If you need those, use a master key.

Master API keys

One per merchant account. Grants full access to /api/merchant/* endpoints — list all payments, manage channels, update settlement wallet/token, etc.

Generate at Settings → Master API Key. Shown once. Store in your secret manager. Rotate or revoke anytime.

GET /api/merchant/payments HTTP/1.1
Host: mutopay.com
Authorization: Bearer msk_live_9c2e...

A master key cannot rotate or revoke itself — that requires a browser JWT session. This is intentional: if your master key leaks, you (the human) can always revoke it from the dashboard, but an attacker holding the leaked key cannot lock you out by rotating it.

Which key should I use?

  • Building a plugin or SDK? → channel key. One key per install.
  • Writing a server-side automation that needs to see all your payments? → master key.
  • Creating payments from multiple distinct integrations? → one channel per integration.

If unsure, start with a channel key. Upgrade to master only when you need account-wide access.

Suspended accounts

If your merchant account is suspended, both channel and master keys return HTTP 403 with {"error": "merchant suspended"}. Contact support to resolve.

See also