# 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.

Source: https://mutopay.com/docs/authentication/
Language: en

---

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

| Credential | Prefix | Header | Use for |
|---|---|---|---|
| Channel API key | `ep_` | `X-API-Key: ep_...` | Creating payments from a specific integration (WooCommerce, mobile app, SaaS billing) |
| Master API key | `msk_` | `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](https://mutopay.com/dashboard/settings). The full key is shown **once**; store it in your secret manager.

Channels come in two modes, picked at creation:

- **Production**: mints keys with the `ep_` prefix. Real on-chain payments, real settlement.
- **Test**: mints keys with the `ep_test_` prefix. Sandbox channel for integration testing: real signed webhooks, no chain interaction, simulate-outcome buttons on the payment page. See [Getting Started → Test before you go live](/docs/getting-started/#test-before-you-go-live).

Mode is permanent on a channel. To go live, create a separate production channel and swap the key in your environment.

Use the channel key on `POST /api/payments`:

```http
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](https://mutopay.com/dashboard/settings). Shown once. Store in your secret manager. Rotate or revoke anytime.

```http
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

- [Master keys vs channel keys](/docs/master-keys-vs-channel-keys/): deeper comparison and rotation guidance.
- [Getting Started](/docs/getting-started/)