# 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[​](#create "Direct link to Create a scoped API key")

Only a user with the **Admin** [role](https://docs.monei.com/manage-account/accessing-your-dashboard.md#roles) 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](https://dashboard.monei.com/settings/api).
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[​](#scopes "Direct link to 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](https://docs.monei.com/apis/rest/payments-create.md) with `paymentToken` or `useDefaultPaymentMethod`, a [recurring payment](https://docs.monei.com/apis/rest/payments-recurring.md) and a [payment confirmation](https://docs.monei.com/apis/rest/payments-confirm.md). 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[​](#limits "Direct link to 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[​](#use "Direct link to 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](https://docs.monei.com/apis/rest.md) and on the [GraphQL API](https://docs.monei.com/apis/graphql.md).

```
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](https://docs.monei.com/monei-connect.md) 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](#signatures) before you remove it.

### Integrations that need the default API key[​](#default-key-integrations "Direct link to Integrations that need the default API key")

The [Wix](https://docs.monei.com/e-commerce/wix.md) and BigCommerce integrations need the default API key. Do not give them a scoped key.

## Keys of connected shop plugins[​](#integration-keys "Direct link to 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[​](#signatures "Direct link to 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](https://docs.monei.com/guides/verify-signature.md).

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[​](#revoke "Direct link to Revoke a scoped API key")

1. Go to [MONEI Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api).
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.