# Claves de API con permisos limitados

Una clave de API con permisos limitados es una clave de API adicional de tu cuenta. Solo llega a los permisos (scopes) que eliges al crearla. Usa una clave con permisos limitados cuando un sistema solo necesita una parte de tu cuenta, por ejemplo un servicio que solo crea y consulta pagos.

Tu clave de API por defecto (`pk_live_` o `pk_test_`) no cambia. Mantiene el acceso completo a tu cuenta.

| Clave                               | Prefijo                | Acceso                       | Cuántas                 |
| ----------------------------------- | ---------------------- | ---------------------------- | ----------------------- |
| Clave de API por defecto            | `pk_live_`, `pk_test_` | Acceso completo a tu cuenta  | Una                     |
| Clave de API con permisos limitados | `mk_live_`, `mk_test_` | Solo los permisos que eliges | Hasta 20 claves activas |

## Crear una clave de API con permisos limitados[​](#create "Enlace directo al Crear una clave de API con permisos limitados")

Solo un usuario con el [rol](https://docs.monei.com/es/manage-account/accessing-your-dashboard.md#roles) **Administrador** puede ver, crear y revocar claves con permisos limitados. Tu cuenta debe poder obtener una clave de API: se aplican las mismas reglas que para la clave de API por defecto.

1. Ve a [MONEI Dashboard → Configuración → Acceso a API](https://dashboard.monei.com/settings/api).
2. En **Claves de API con permisos limitados**, haz clic en **Crear clave de API con permisos limitados**.
3. Escribe un nombre para la clave, por ejemplo el nombre del sistema que la usa.
4. Elige los permisos. La clave solo llega a estos permisos.
5. Crea la clave. El panel muestra la **Clave secreta** (`mk_live_…` o `mk_test_…`) y su **Secreto de firma** (`mksec_…`).
6. Copia los dos valores y guárdalos en un lugar seguro.

Solo se muestran una vez

MONEI muestra la clave secreta y el secreto de firma solo una vez. MONEI no puede mostrarlos de nuevo. Si los pierdes, revoca la clave y crea una nueva.

Una clave creada en modo de prueba empieza por `mk_test_` y solo funciona en tu cuenta de prueba. Una clave creada en modo real empieza por `mk_live_`. La lista de claves muestra cada clave como `mk_live_…abcd` (los 4 últimos caracteres).

## Permisos[​](#scopes "Enlace directo al Permisos")

Un permiso se escribe como `recurso:acción` (por ejemplo `payments:create` o `payments:read`). El panel muestra cada permiso que puede tener una clave, con una etiqueta. Una solicitud fuera de los permisos de la clave falla.

`payments:create` también cobra un método de pago guardado: un [pago](https://docs.monei.com/es/apis/rest/payments-create.md) con `paymentToken` o `useDefaultPaymentMethod`, un [pago recurrente](https://docs.monei.com/es/apis/rest/payments-recurring.md) y una [confirmación de pago](https://docs.monei.com/es/apis/rest/payments-confirm.md). Dalo solo a un sistema que pueda cobrar a tus clientes.

No puedes editar los permisos de una clave. Para cambiarlos, crea una clave nueva con los permisos nuevos, pasa tu sistema a ella y después revoca la clave anterior.

Tres permisos tienen la etiqueta **Solo API REST**. Abren rutas REST que no tienen operación GraphQL:

| Permiso                      | Rutas REST                        |
| ---------------------------- | --------------------------------- |
| `allowedPaymentMethods:read` | `GET /v1/allowed-payment-methods` |
| `applePayDomains:write`      | `POST /v1/apple-pay/domains`      |
| `pmsTokens:create`           | `POST /v1/partner/tokens`         |

### Lo que una clave con permisos limitados nunca puede hacer[​](#limits "Enlace directo al Lo que una clave con permisos limitados nunca puede hacer")

Ningún permiso da estas acciones a una clave con permisos limitados. Usa el panel o la clave de API por defecto para ellas.

* Ver o cambiar una cuenta bancaria (IBAN). En GraphQL, los IBAN aparecen enmascarados. En REST, una solicitud que envía `iban` a una tienda falla, y la respuesta enmascara el IBAN de la tienda.
* Ver las credenciales de un procesador de pagos.
* Cambiar procesadores de pagos, webhooks o ajustes de la cuenta.
* Gestionar usuarios.
* Obtener un token de autenticación POS para MONEI Pay.
* Ver, crear o revocar claves de API.
* Crear un payout (tipo de transacción `PAYOUT`) en una cuenta real. La solicitud falla.

## Usar una clave de API con permisos limitados[​](#use "Enlace directo al Usar una clave de API con permisos limitados")

Envía la clave en la cabecera `Authorization`, igual que la clave de API por defecto. Una clave con permisos limitados funciona en la [API REST](https://docs.monei.com/es/apis/rest.md) y en la [API GraphQL](https://docs.monei.com/es/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>'
```

| Caso                                         | API REST           | API GraphQL                                                  |
| -------------------------------------------- | ------------------ | ------------------------------------------------------------ |
| Clave desconocida o revocada                 | `401 Unauthorized` | `Unauthorized`                                               |
| Operación fuera de los permisos de la clave  | `403 Forbidden`    | `Unauthorized` con el mensaje `Not authorized: <permission>` |
| Solicitud con la cabecera `MONEI-Account-ID` | `403 Forbidden`    | `Unauthorized`                                               |

Una clave con permisos limitados siempre actúa sobre su propia cuenta. Un socio de [MONEI Connect](https://docs.monei.com/es/monei-connect.md) no puede enviar una clave con permisos limitados con la cabecera `MONEI-Account-ID` para actuar por la cuenta de un comercio. Los socios usan su clave de API de socio.

Tu cuenta no necesita una clave de API por defecto para usar una clave con permisos limitados. Lee [Callbacks y webhooks](#signatures) antes de eliminarla.

### Integraciones que necesitan la clave de API por defecto[​](#default-key-integrations "Enlace directo al Integraciones que necesitan la clave de API por defecto")

Las integraciones de [Wix](https://docs.monei.com/es/e-commerce/wix.md) y BigCommerce necesitan la clave de API por defecto. No les des una clave con permisos limitados.

## Claves de plugins de tienda conectados[​](#integration-keys "Enlace directo al Claves de plugins de tienda conectados")

Un plugin de WooCommerce, PrestaShop o Magento (Adobe Commerce) que conectas a MONEI obtiene su propia clave con permisos limitados. La lista de claves muestra la plataforma y el host de la tienda de cada una de estas claves, por ejemplo "WooCommerce: shop.example.com".

* La clave solo tiene los permisos que necesita el plugin.
* La clave solo funciona en la API REST. Una solicitud GraphQL con ella falla.
* Si conectas la tienda de nuevo, el plugin obtiene una clave nueva. La clave anterior sigue siendo válida hasta que la revocas.

## Callbacks y webhooks[​](#signatures "Enlace directo al Callbacks y webhooks")

MONEI firma los callbacks y los webhooks en la cabecera `MONEI-Signature`. La firma `v1` usa la clave de API por defecto de tu cuenta. Esto no cambia para los pagos que crea una clave con permisos limitados. Para verificar `v1`, consulta [Verificar firma](https://docs.monei.com/es/guides/verify-signature.md).

Un sistema que solo tiene una clave con permisos limitados no puede verificar `v1`. Para obtener un estado fiable, puede consultar el pago con `GET /v1/payments/{id}` (permiso `payments:read`) cuando llega un callback.

Firmas con el secreto de firma

Pronto habrá una firma `v2`. MONEI la firmará con el secreto de firma de la clave con permisos limitados que creó la operación. Hasta entonces, el secreto de firma no tiene uso. Guárdalo con la clave.

Hasta que `v2` esté disponible, un callback de un pago que crea una clave con permisos limitados en una cuenta sin clave de API por defecto no tiene firma. Su cuerpo solo contiene `id`, `amount`, `currency`, `orderId`, `status` y `statusMessage`. Consulta el pago con la API para obtener los demás campos.

## Revocar una clave de API con permisos limitados[​](#revoke "Enlace directo al Revocar una clave de API con permisos limitados")

1. Ve a [MONEI Dashboard → Configuración → Acceso a API](https://dashboard.monei.com/settings/api).
2. En **Claves de API con permisos limitados**, busca la clave y haz clic en **Revocar**.
3. Confirma.

Las solicitudes con la clave fallan desde ese momento. Un plugin de tienda que usa la clave deja de aceptar pagos. No puedes deshacer una revocación.

Una clave con permisos limitados no caduca. Solo una revocación la termina. Revoca una clave cuando ya no la usas, o cuando crees que otra persona la tiene.