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
Solo un usuario con el rol 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.
- Ve a MONEI Dashboard → Configuración → Acceso a API.
- En Claves de API con permisos limitados, haz clic en Crear clave de API con permisos limitados.
- Escribe un nombre para la clave, por ejemplo el nombre del sistema que la usa.
- Elige los permisos. La clave solo llega a estos permisos.
- Crea la clave. El panel muestra la Clave secreta (
mk_live_…omk_test_…) y su Secreto de firma (mksec_…). - Copia los dos valores y guárdalos en un lugar seguro.
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
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 con paymentToken o useDefaultPaymentMethod, un pago recurrente y una confirmación de pago. 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
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
ibana 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
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 y en la API GraphQL.
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 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 antes de eliminarla.
Integraciones que necesitan la clave de API por defecto
Las integraciones de Wix y BigCommerce necesitan la clave de API por defecto. No les des una clave con permisos limitados.
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
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.
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.
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
- Ve a MONEI Dashboard → Configuración → Acceso a API.
- En Claves de API con permisos limitados, busca la clave y haz clic en Revocar.
- 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.