# Claves de API restringidas

Usa claves de API restringidas para controlar el acceso de tu solicitud a la API Stripe.

Puedes usar una clave de API restringida (RAK) para asignar permisos de API específicos de Stripe a tus claves API. El uso de una RAK como esta limita el daño potencial a tu empresa si una clave API se expone a un actor incorrecto. Si una clave API restringida no tiene los permisos correctos para completar una solicitud de API, Stripe emite 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 una cuenta en Stripe, obtienes una [clave de API secreta](https://docs.stripe.com/keys.md#obtain-api-keys) (que comienza con `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 de API restringida (RAK) comienza con `rk_live_` o `rk_test_` y solo puede hacer lo que elijas. Cuando creas una RAK en el Dashboard de Stripe, seleccionas 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 de API restringidas.

Puedes usar claves restringidas como medida defensiva para proteger tu cuenta de Stripe en caso de que tus claves queden expuestas o comprometidas. Si un actor incorrecto obtiene una clave de API restringida, se limita a los permisos de esa clave. Por ejemplo, podrías crear una clave restringida que solo pueda leer datos disputados y nada más. Si un actor incorrecto obtuvo esa clave, solo podría leer datos disputados. No podría crear cargos, acceder métodos de pago clientes ni activar transferencias.

Stripe recomienda utilizar siempre claves restringidas en lugar de claves secretas no restringidas. Sigue siempre prácticas recomendadas cuando utilices claves restringidas para evitar exposiciones accidentales o compromisos indeseados. Consulta las [prácticas recomendadas para gestionar claves de API secretas](https://docs.stripe.com/keys-best-practices.md).

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

|                                    | Clave secreta (`sk_`)                                | Clave restringida (`rk_`)                                          |
| ---------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
| **Alcance del acceso**             | Acceso completo a todos los recursos de la API       | Solo los permisos que asignes                                      |
| **Impacto si se ve comprometido**  | Un mal actor puede hacer cualquier cosa en tu cuenta | Un mal actor solo puede hacer lo que permite la clave              |
| **Intercambio con terceros**       | Peligroso: otorga el control total al tercero        | Más seguro: otorgas solo el acceso que necesita el tercero         |
| **Principio de privilegio mínimo** | No es posible lograrlo con claves no restringidas    | Puedes otorgar permisos mínimos a las claves                       |
| **Recomendación de Stripe**        | Usar con moderación y proteger agresivamente         | **Preferido**: utiliza claves restringidas siempre que sea posible |

### Motivos para cambiar a claves de API restringidas

- **Limita el impacto de una posible apropiación de claves**: si una clave restringida se ve comprometida, un mal actor puede acceder solo a los recursos específicos a los que le permitiste acceder a esa clave.

- **Comparte claves con terceros de forma segura**: Stripe desaconseja compartir claves en la mayoría de las circunstancias, pero en el caso de ciertas integraciones de terceros, es posible que tengas que compartir una clave. Por ejemplo, si un proveedor necesita supervisar tus disputas, dale una clave restringida con acceso a disputas de solo lectura, no tu clave secreta ilimitada. Si trabajas con un tercero, asegúrate de que siga las [prácticas recomendadas](https://docs.stripe.com/keys-best-practices.md) para administrar la clave de forma segura, como usar una lista de permitidos de IP si es posible para mitigar el riesgo de que la clave se vea comprometida y venza si la relación termina.

- **Cumple con las expectativas de cumplimiento de la normativa**: muchas auditorías de seguridad y marcos de cumplimiento de la normativa esperan que sigas el principio de privilegio mínimo. Con las claves restringidas, es más sencillo.

- **Combinar con restricciones de IP**: puedes bloquear cualquier clave restringida a un conjunto específico de direcciones IP para una capa adicional de defensa.

## Migra de una clave secreta a una clave restringida

Las claves de API restringidas son reemplazos insertables de las claves de API secretas. Para usar una clave de API restringida, proporciónala a tu código de la misma manera que proporcionaste tu clave secreta, siguiendo [prácticas recomendadas](https://docs.stripe.com/keys-best-practices.md) para evitar que la clave quede expuesta de forma accidental. Todas las API Stripe admiten claves API restringidas. Debes configurar los permisos de cada clave restringida para obtener los beneficios.

A continuación, te presentamos un enfoque paso a paso para migrar de una clave secreta a una clave restringida. Consulta [Asignar permisos a una clave de API restringida](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions) para entender cómo reducir los permisos de una clave restringida.

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

Revisa tu código y cualquier integración de terceros para catalogar los productos Stripe que usas y las llamadas API que realizas actualmente con tu clave secreta.

Revisa los [registros de solicitudes de la clave secreta en Workbench](https://dashboard.stripe.com/workbench/logs). Puedes usar la siguiente tabla para asignar las solicitudes de API correctas a los permisos RAK que necesitan.

| Método HTTP       | Tipo de permiso RAK |
| ----------------- | ------------------- |
| GET (OBTENER)     | leer                |
| POST (PUBLICAR)   | escribir            |
| DELETE (ELIMINAR) | escribir            |

Por ejemplo, si ves llamadas exitosas a `GET /v1/customers`, debes agregar permisos de lectura para el recurso [cliente](https://docs.stripe.com/api/customers.md) a los permisos de una RAK de reemplazo.

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

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

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

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

En tu solicitud de prueba o clasificación, reemplaza la clave secreta por la clave restringida en el entorno de tu servidor (por ejemplo, en una variable de entorno o en una bóveda de secretos). Las llamadas SDK y HTTP de Stripe que usan tu clave funcionan de manera idéntica. 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 de la [lista de claves](https://dashboard.stripe.com/apikeys) haciendo clic en el menú de contenido adicional (⋯) 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 agregar las acciones que fallaron:

1. Haz clic en el menú de contenido adicional (⋯) junto a la clave.
1. Selecciona **Editar clave**.
1. Repite tus pruebas en un entorno de prueba para confirmar que le asignaste los permisos correctos a la clave restringida.

Revisa los registros de tu solicitud en busca de errores de la API Stripe. Si la clave restringida enviada con una solicitud no tiene los permisos correctos, el cuerpo de respuesta incluye un mensaje de error que explica qué permisos agregar.

### Crear una clave restringida en modo activo

Crea una nueva clave restringida en modo activo con permisos que coincidan con la clave en modo de prueba que probaste.

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

Usa la clave nueva en tu entorno de producción de la misma manera que configuraste la clave de prueba en tu entorno de preparación.

### Retirar 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 [pasa a desuso](https://docs.stripe.com/keys.md#delete-secret-key) tu antigua clave secreta en el Dashboard. Esto garantiza que nadie pueda usarla en el futuro. Puedes establecer un vencimiento diferido (hasta 7 días) si quieres una ventana de seguridad durante la cual aún puedas volver a la clave secreta.

## Asignar permisos a una clave API restringida

Puedes configurar claves restringidas para que se ajusten a tus casos de uso específicos de acuerdo con el principio de privilegio mínimo: una clave debe tener los permisos mínimos necesarios para hacer su trabajo y no más. A continuación, te presentamos varios enfoques prácticos para asignar permisos.

### Registros de solicitudes de auditoría para determinar los permisos

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

Revisa los puntos de conexión de la API que usó tu aplicación durante tus pruebas con la clave restringida para ver exactamente qué recursos usó tu aplicación y si los leíste o escribiste:

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

Si tu solicitud funcionó correctamente en tus pruebas, haz una lista de las llamadas exitosas en los registros de solicitudes y, luego, compara la lista con los permisos que otorgaste a la clave restringida. Puedes eliminar los permisos que tu clave no utilizó. Para editar los permisos de la clave:

1. Haz clic en el menú de contenido adicional (⋯).
1. Haz clic en **Editar clave**.

Si tu solicitud no funciona correctamente, puedes filtrar los registros de solicitudes de la clave para mostrar solicitudes fallidas. Luego, edita los permisos de la clave en el menú de claves para agregar los permisos de API Stripe correspondientes.

### Revisa tu código

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

- `PaymentIntent.create(...)` → **PaymentIntents: Escribir**
- `Customer.retrieve(...)` → **Clientes: Leer**
- `Disputar.list(...)` → **Disputas: Leer**

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

### Comienza con permisos amplios y luego elimina lo que no necesites

Inicialmente, puedes darle permisos amplios a una clave restringida y luego eliminar cualquier exceso de permisos después de revisar cómo se usa 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 API Stripe no incluye una categoría en particular, como Stripe Billing, puedes seleccionar **Ninguno** para esa categoría. De lo contrario, selecciona **Escritura** para categorías que sean relevantes para tu consumo de API Stripe. Los permisos **Escritura** incluyen permisos **Lectura**: si una clave puede escribir un recurso API, también puede leer ese recurso.

Prueba tu solicitud con la clave restringida en modo de prueba, como se describió anteriormente, para que tu solicitud use la clave para hacer solicitudes de API Stripe. Prueba cada componente de tu solicitud que use las API Stripe.

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

Si tienes varios servicios que usan las API Stripe (por ejemplo, un servicio de facturación, un servicio de elaboración de informes y un controlador de webhooks), crea una clave restringida separada para cada servicio y dale a cada clave solo los permisos API Stripe que cada servicio necesita. Otorgar permisos separados te permite limitar el impacto potencial de una apropiación de clave si alguno de tus servicios se ve comprometido.