Scoped API keys

A scoped API key is an additional API key of your account. It reaches only the scopes that you select when you create it. Use a scoped key when a system needs only part of your account, for example a service that only creates and reads payments.

Your default API key (pk_live_ or pk_test_) does not change. It keeps full access to your account.

Key	Prefix	Access	How many
Default API key	pk_live_, pk_test_	Full access to your account	One
Scoped API key	mk_live_, mk_test_	Only the scopes you select	Up to 20 active keys

Create a scoped API key

Only a user with the Admin role can see, create and revoke scoped API keys. Your account must be able to get an API key: the same rules apply as for the default API key.

1. Go to MONEI Dashboard → Settings → API Access.
2. In Scoped API keys, click Create scoped API key.
3. Enter a name for the key, for example the name of the system that uses it.
4. Select the scopes. The key reaches only these scopes.
5. Create the key. The dashboard shows the Secret key (mk_live_… or mk_test_…) and its Signing secret (mksec_…).
6. Copy both values and keep them in a safe place.

Shown only once

MONEI shows the secret key and the signing secret only once. MONEI cannot show them again. If you lose them, revoke the key and create a new one.

A key made in test mode starts with mk_test_ and works on your test account only. A key made in live mode starts with mk_live_. The list of keys shows each key as mk_live_…abcd (the last 4 characters).

Scopes

A scope is a permission, written as resource:action (for example payments:create or payments:read). The dashboard lists each scope that a key can get, with a label. A request outside the scopes of the key fails.

payments:create also charges a saved payment method: a payment with paymentToken or useDefaultPaymentMethod, a recurring payment and a payment confirmation. Give it only to a system that may charge your customers.

You cannot edit the scopes of a key. To change them, create a new key with the new scopes, move your system to it, then revoke the old key.

Three scopes have the label REST API only. They open REST routes that have no GraphQL operation:

Scope	REST routes
allowedPaymentMethods:read	GET /v1/allowed-payment-methods
applePayDomains:write	POST /v1/apple-pay/domains
pmsTokens:create	POST /v1/partner/tokens

What a scoped key can never do

No scope gives a scoped key these actions. Use the dashboard or the default API key for them.

• Read or change a bank account (IBAN). On GraphQL, IBANs are masked. On REST, a request that sends iban to a store fails, and the response masks the store IBAN.
• Read the credentials of a payment processor.
• Change payment processors, webhooks or account settings.
• Manage users.
• Get a POS auth token for MONEI Pay.
• See, create or revoke API keys.
• Create a payout (transaction type PAYOUT) on a live account. The request fails.

Use a scoped API key

Send the scoped key in the Authorization header, as you send the default API key. A scoped key works on the REST API and on the GraphQL API.

curl --request GET 'https://api.monei.com/v1/payments/<PAYMENT_ID>' \
--header 'Authorization: mk_live_<YOUR_SCOPED_API_KEY>' \
--header 'User-Agent: MONEI/<YOUR_APP>/<VERSION>'

Case	REST API	GraphQL API
Unknown or revoked key	401 Unauthorized	Unauthorized
Operation outside the scopes of the key	403 Forbidden	Unauthorized with the message Not authorized: <permission>
Request with a MONEI-Account-ID header	403 Forbidden	Unauthorized

A scoped key always acts on its own account. A MONEI Connect partner cannot send a scoped key with the MONEI-Account-ID header to act for a merchant account. Partners use their Partner API Key.

Your account does not need a default API key to use a scoped key. Read Callbacks and webhooks before you remove it.

Integrations that need the default API key

The Wix and BigCommerce integrations need the default API key. Do not give them a scoped key.

Keys of connected shop plugins

A WooCommerce, PrestaShop or Magento (Adobe Commerce) plugin that you connect to MONEI gets its own scoped API key. The list of scoped keys shows the platform and the shop host of each such key, for example "WooCommerce: shop.example.com".

• The key has only the scopes that the plugin needs.
• The key works on the REST API only. A GraphQL request with it fails.
• If you connect the shop again, the plugin gets a new key. The old key stays valid until you revoke it.

Callbacks and webhooks

MONEI signs callbacks and webhooks in the MONEI-Signature header. The v1 signature uses your account's default API key. This does not change for payments that a scoped key creates. To verify v1, see Verify signature.

A system that holds only a scoped key cannot verify v1. To get a trusted status, it can read the payment with GET /v1/payments/{id} (scope payments:read) when a callback arrives.

Signatures with the signing secret

A v2 signature is coming. MONEI will sign it with the signing secret of the scoped key that created the operation. Until then, the signing secret has no use. Keep it with the key.

Until v2 is available, a callback for a payment that a scoped key creates on an account with no default API key has no signature. Its body holds only id, amount, currency, orderId, status and statusMessage. Read the payment with the API to get the other fields.

Revoke a scoped API key

1. Go to MONEI Dashboard → Settings → API Access.
2. In Scoped API keys, find the key and click Revoke.
3. Confirm.

Requests with the key fail from that moment. A shop plugin that uses the key stops taking payments. You cannot undo a revoke.

A scoped key does not expire. Only a revoke ends it. Revoke a key when you no longer use it, or when you think that someone else has it.