# Claves de API restringidas

Utiliza claves API restringidas para controlar el acceso de tu aplicación a la API de Stripe.

Puedes utilizar una clave API restringida (RAK) para asignar permisos específicos de la API de Stripe a tus claves API. El uso de una RAK de este modo limita el daño potencial para tu empresa en caso de que una clave API caiga en manos de personas malintencionadas. Si una clave API restringida no cuenta con los permisos adecuados para completar una solicitud de API, Stripe devuelve un [error de solicitud no válida](https://docs.stripe.com/error-handling.md#invalid-request-errors).

## ¿Qué es una clave de API restringida?

Cuando creas tu cuenta en Stripe, obtienes una [clave API secreta](https://docs.stripe.com/keys.md#obtain-api-keys) (que empieza por `sk_live_` o `sk_test_`). Cualquier persona, agente o sistema con tu clave secreta puede hacer *anything* en tu cuenta de Stripe: crear cargos, emitir reembolsos, leer datos de clientes, activar transferencias y mucho más.

Una clave API restringida (RAK) comienza con `rk_live_` o `rk_test_` y solo puede realizar las acciones que tú elijas. Al crear una RAK en el Dashboard de Stripe, debes seleccionar a qué recursos de Stripe puede acceder la clave y los permisos para cada recurso: **Lectura**, **Escritura** o **Ninguno**. Todas las API de Stripe admiten claves API restringidas.

Puedes utilizar claves restringidas como medida de seguridad para proteger tu cuenta de Stripe en caso de que tus claves se vean expuestas o comprometidas. Si un usuario malintencionado obtiene una clave API restringida, sus acciones se limitarán a los permisos de dicha clave. Por ejemplo, podrías crear una clave restringida que solo permita leer datos de disputas y nada más. Si un usuario malintencionado obtuviera esa clave, solo podría leer datos de disputas. No podría crear cargos, acceder a los métodos de pago de los clientes ni activar pagos.

Stripe recomienda utilizar siempre claves restringidas en lugar de claves secretas sin restricciones. Sigue siempre las prácticas recomendadas al utilizar claves restringidas para evitar su exposición o compromiso accidental. Consulta [Prácticas recomendadas para la gestión de claves secretas de API](https://docs.stripe.com/keys-best-practices.md).

## ¿Por qué usar claves restringidas en lugar de claves secretas?

|                                             | Clave secreta (`sk_`)                                             | Clave restringida (`rk_`)                                            |
| ------------------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Ámbito de acceso**                        | Acceso completo a todos los recursos de API                       | Solo los permisos que asignes                                        |
| **Consecuencias en caso de vulnerabilidad** | Un usuario malintencionado puede hacer lo que quiera en tu cuenta | Un malintencionado solo puede hacer lo que le permita la clave       |
| **Compartir con terceros**                  | Peligroso: otorga el control total al tercero                     | Más seguro: solo ofreces el acceso que necesita el tercero           |
| **Principio de privilegios mínimos**        | No es posible lograrlo con claves sin restricciones               | Puedes asignar permisos mínimos a las claves                         |
| **Recomendación de Stripe**                 | Úsalo con moderación y protégete a fondo                          | **Recomendado**: utiliza claves restringidas siempre que sea posible |

### Razones para pasar a las claves API restringidas

- **Limita el impacto de una posible apropiación de una clave**: si una clave restringida se ve comprometida, un atacante solo podrá acceder a los recursos específicos a los que usted haya permitido el acceso a dicha clave.

- **Comparte claves de forma segura con terceros**: Stripe desaconseja compartir claves en la mayoría de los casos, pero para determinadas integraciones con terceros, es posible que tengas que compartir una clave. Por ejemplo, si un proveedor necesita supervisar tus disputas, facilítale una clave restringida con acceso de solo lectura a las disputas, no tu clave secreta sin restricciones. Si trabajas con un tercero, asegúrate de que siga las [prácticas recomendadas](https://docs.stripe.com/keys-best-practices.md) para gestionar la clave de forma segura, como utilizar una lista de direcciones IP permitidas si es posible para mitigar el riesgo de que la clave se vea comprometida y caducar la clave si la relación finaliza.

- **Cumple con los requisitos de cumplimiento normativo**: muchas auditorías de seguridad y marcos de cumplimiento de la normativa exigen que se respete el principio del privilegio mínimo. Las claves restringidas facilitan esta tarea.

- **Combínalo con restricciones de IP**: puedes limitar cualquier clave restringida a un conjunto específico de direcciones IP para añadir una capa adicional de protección.

## Migra de una clave secreta a una clave restringida

Las claves API restringidas son sustitutos directos de las claves API secretas. Para utilizar una clave API restringida, introdúcela en tu código del mismo modo que lo harías con una clave secreta, siguiendo las [prácticas recomendadas](https://docs.stripe.com/keys-best-practices.md) para evitar exponerla accidentalmente. Todas las API de Stripe admiten claves API restringidas. Para aprovechar sus ventajas, debes configurar los permisos de cada clave restringida.

A continuación se describe un procedimiento paso a paso para pasar de una clave secreta a una clave restringida. Consulta [Asignar permisos a una clave API restringida](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions) para saber cómo reducir los permisos de una clave restringida.

### Revisa el consumo de API de la clave secreta

Revisa tu código y cualquier integración de terceros para hacer un inventario de los productos de Stripe que utilizas y de las llamadas a la API que realizas actualmente con tu clave secreta.

Revisa los registros de [peticiones de la clave secreta en Workbench](https://dashboard.stripe.com/workbench/logs). Puedes utilizar la tabla siguiente para relacionar las solicitudes de API correctas con los permisos RAK que requieren.

| Método HTTP | Tipo de permiso RAK |
| ----------- | ------------------- |
| OBTENER     | leer                |
| PUBLICAR    | escribir            |
| ELIMINAR    | escribir            |

Por ejemplo, si observas que se realizan llamadas con éxito a `GET /v1/customers`, debes añadir permisos de lectura para el recurso [Cliente](https://docs.stripe.com/api/customers.md) a los permisos de un RAK sustitutivo.

### Crear una clave restringida en un entorno de pruebas

Stripe recomienda crear una clave restringida en un entorno de prueba de Stripe antes de crear una clave para el modo activo.

1. Ve a la [página Claves API](https://dashboard.stripe.com/apikeys) del Dashboard de Stripe.
1. Haz clic en **Crear clave restringida**.
1. Ponle un nombre descriptivo, como `billing-service-test`.
1. Para cada recurso, configura el permiso como **Ninguno**, **Lectura** o **Escritura** según el consumo de la API que hayas observado anteriormente.

### Configura tu entorno de prueba para que utilice la clave restringida

En tu aplicación de prueba o de desarrollo, sustituye la clave secreta por la clave restringida de tu entorno de servidor (por ejemplo, en una variable de entorno o en un almacén de secretos). El SDK de Stripe y las llamadas HTTP que utilizan tu clave funcionan exactamente igual. La única diferencia es el valor de la clave.

### Revisa los registros de solicitudes de la clave restringida en busca de errores y ajusta los permisos

Revisa los registros de la clave restringida en modo de prueba desde la [lista de claves](https://dashboard.stripe.com/apikeys) haciendo clic en el menú desplegable (⋯) situado junto a la clave y seleccionando **Ver registros de solicitudes**.

Si encuentras algún mensaje de error, como `ERR 403`, edita los permisos de la clave restringida para añadir las acciones que han fallado:

1. Haz clic en el menú desplegable (⋯) situado junto a la tecla.
1. Selecciona **Editar clave**.
1. Repite las pruebas en un entorno de pruebas para confirmar que has asignado los permisos correctos a la clave restringida.

Comprueba los registros de tu aplicación para ver si hay errores de la API de Stripe. Si la clave restringida enviada con una solicitud no tiene los permisos correctos, el cuerpo de la respuesta incluye un mensaje de error en el que se explica qué permisos hay que añadir.

### Crear una clave restringida en modo activo

Crea una nueva clave restringida en modo activo con los mismos permisos que la clave de modo de prueba que has probado.

### Configura tu entorno de producción para usar la clave restringida

Utiliza la nueva clave en tu entorno de producción del mismo modo que configuraste la clave de prueba en tu entorno de prueba.

### Retira la antigua clave secreta

Cuando estés seguro de que todo funciona en modo de prueba, [rota](https://docs.stripe.com/keys.md#rolling-keys) o [caduca](https://docs.stripe.com/keys.md#delete-secret-key) tu clave secreta antigua en el Dashboard. De este modo, te aseguras de que nadie pueda utilizarla en el futuro. Puedes configurar una caducidad diferida (hasta 7 días) si deseas disponer de un margen de seguridad durante el cual aún puedas volver a utilizar la clave secreta.

## Asignar permisos a una clave API restringida

Puedes configurar claves con restricciones para adaptarlas a tus casos de uso específicos, siguiendo el principio del privilegio mínimo: una clave debe tener los permisos mínimos necesarios para cumplir su función, y nada más. A continuación te presentamos varios enfoques prácticos para asignar permisos.

### Audita registros de peticiones para determinar los permisos

1. Ve a la página de [claves de API](https://dashboard.stripe.com/apikeys) del Dashboard.
1. Busca la clave restringida que estás configurando.
1. Haz clic en el menú desplegable (⋯) situado junto a la tecla.
1. Haz clic en **Ver registros peticiones** para ver todas las peticiones realizadas con esa clave.

Revisa los puntos de conexión de la API que utilizó tu aplicación durante las pruebas con la clave restringida para ver exactamente qué recursos utilizó y si se realizaron operaciones de lectura o escritura en ellos:

- Las peticiones `GET` son lecturas
- Las solicitudes `POST` y `DELETE` son escrituras

Si tu aplicación ha funcionado correctamente durante las pruebas, haz una lista de las llamadas que se han realizado con éxito en los registros de solicitudes y compárala con los permisos que has concedido a la clave restringida. Puedes eliminar cualquier permiso que tu clave no haya utilizado. Para editar los permisos de la clave:

1. Haz clic en el menú desplegable (⋯).
1. Haz clic en **Editar clave**.

Si tu aplicación no funciona correctamente, puedes filtrar los registros de solicitudes de la clave para ver las solicitudes fallidas y, a continuación, editar los permisos de la clave en el menú de claves para añadir los permisos correspondientes de la API de Stripe.

### Revisa tu código

Puedes crear una lista de los permisos necesarios buscando en tu código las llamadas al SDK de Stripe. Asigna cada llamada al permiso correspondiente en el Dashboard. Por ejemplo:

- `PaymentIntent.create(...)` → **PaymentIntents: Write**
- `Customer.retrieve(...)` → **Customers: Read**
- `Dispute.list(...)` → **Disputes: Read**

Luego, configura los permisos de tu clave restringida para que coincidan solo con los que encontraste.

### Empieza con permisos amplios y, a continuación, elimina lo que no necesites

En un primer momento, puedes conceder amplios permisos a una clave restringida y, posteriormente, eliminar los permisos innecesarios tras analizar cómo se utiliza la clave.

En un entorno de pruebas, crea una clave restringida desde el menú de claves de API. Los permisos disponibles están agrupados en categorías. Si sabes que tu consumo de la API de Stripe no incluye una categoría concreta, como Stripe Billing, puedes seleccionar **Ninguno** para esa categoría. De lo contrario, selecciona **Escritura** para las categorías que sean relevantes para tu uso de la API de Stripe. Los permisos de **Escritura** incluyen los permisos de **Lectura**: si una clave puede escribir en un recurso de la API, también puede leer ese recurso.

Prueba tu aplicación con la clave restringida del modo de prueba, tal y como se ha descrito anteriormente, para que tu aplicación utilice dicha clave al realizar solicitudes a la API de Stripe. Prueba todos los componentes de tu aplicación que utilicen las API de Stripe.

## Utiliza una clave restringida por servicio o caso de uso

Si tienes varios servicios que utilizan las API de Stripe (por ejemplo, un servicio de facturación, un servicio de generación de informes y un gestor de webhooks), crea una clave restringida independiente para cada servicio y asigna a cada clave únicamente los permisos de la API de Stripe que necesite cada servicio. Otorgar permisos independientes te permite limitar el impacto potencial de una apropiación de la clave en caso de que alguno de tus servicios se vea comprometido.