# 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 específicos de la API de Stripe a tus claves de API. Las RAK son el tipo de clave recomendado para [las claves de API que les proporcionas a los agentes de IA](https://docs.stripe.com/keys.md#agent-keys). El uso de una RAK limita el daño potencial a tu empresa si una clave de API queda expuesta a un actor malintencionado. Si una clave de 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?

Una clave de API restringida (RAK) es una clave de API que tus aplicaciones del lado del servidor incluyen en las solicitudes a la API de Stripe. Una RAK comienza con `rk_live_` o `rk_test_`. A diferencia de una clave secreta que puede hacer cualquier cosa en tu cuenta de Stripe, una RAK puede hacer solo lo que le otorgues permiso para hacer. 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.

Usa claves RAK 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 RAK, se limita a los permisos de esa clave. Por ejemplo, podrías crear una clave RAK 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 a métodos de pago de clientes ni activar transferencias.

Stripe recomienda usar siempre RAK en lugar de claves secretas sin restricciones, en particular cuando se le da una clave a un agente de IA. Usa los permisos RAK para limitar lo que un agente puede hacer en tu cuenta.

Sigue siempre las [prácticas recomendadas](https://docs.stripe.com/keys-best-practices.md) cuando uses RAK para evitar exposiciones accidentales o comprometer tu negocio. Trata los RAK con la misma precaución que las claves API secretas.

## ¿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 |
| **Adecuación para agentes de IA** | Un agente puede hacer cosas que no quieres en tu cuenta | Controlas explícitamente los permisos del agente |
| **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 |
| **Cumplimiento de la normativa** | Puedes controlar quién tiene acceso a tus claves, pero no lo que las claves pueden hacer | Puedes controlar quién tiene acceso a tus claves y controlar lo que esas claves pueden hacer |
| **Recomendación de Stripe** | Usar con moderación y proteger agresivamente | **Preferido**: utiliza claves restringidas siempre que sea posible |

## Cómo crear una clave de API restringida

1. En la pestaña [Claves de API](https://dashboard.stripe.com/apikeys), realiza una de las siguientes acciones:
   - Para crear una nueva clave restringida, haz clic en **Crear clave restringida**.
   - Para clonar una clave que ya existe, haz clic en el menú de opciones (⋯) y, a continuación, selecciona **Duplicar clave**. En este caso, el valor predeterminado para cada permiso es su valor en la clave clonada.
2. Si creas una nueva clave, puedes elegir entre un conjunto de permisos preconfigurados o comenzar sin ningún permiso.
3. En el campo **Nombre de la clave**, ingresa un nombre. Si clonaste una clave existente, el nombre predeterminado es el nombre de la clave clonada.
4. Para cada recurso al que deseas que acceda la nueva clave, selecciona el permiso apropiado: **Ninguno**, **Lectura** o **Escritura**. Si usas Connect, también puedes seleccionar el permiso para que esta clave lo permita cuando se acceda a las cuentas conectadas. El valor predeterminado para todos los permisos es **Ninguno**.
5. Haz clic en **Crear clave**.
6. En el cuadro de diálogo, completa la verificación de dos factores que te enviamos.
7. Haz clic en el valor clave para copiarlo.
8. Guarda el valor de la clave. No puedes recuperarlo más tarde.
9. En el campo **Agregar una nota**, ingresa la ubicación donde guardaste la clave y haz clic en **Listo**.

## Migra de una clave secreta a una clave restringida

En tu entorno de servidor, 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 de Stripe admiten claves API restringidas. Debes configurar los permisos de cada clave restringida para obtener los beneficios.

Las siguientes secciones describen 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.

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

Crea una clave de API restringida en un [entorno de prueba](https://docs.stripe.com/keys.md#test-live-modes) antes de crear una clave en modo activo.

1. En la [página de claves de API](https://dashboard.stripe.com/apikeys) del Dashboard de Stripe, haz clic en **Crear clave restringida**.
2. Dale a la nueva clave un nombre descriptivo, como `billing-service-test`.
3. No le asignes ningún permiso a la clave por ahora. Los permisos se configuran después de revisar el uso existente de la clave secreta.

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

Utiliza el uso actual de la API de la clave secreta como referencia para configurar los permisos de una RAK.

- 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](https://docs.stripe.com/keys.md#view-request-logs) de la clave secreta para ver las solicitudes de API exitosas.

Usa la tabla a continuación para asignar las solicitudes de API exitosas a los permisos que necesita tu RAK. Para cada recurso, configura el permiso en **Ninguno**, **Lectura** o **Escritura** según el consumo de API que observaste. Los permisos de escritura implican permisos de lectura: cualquier clave que pueda escribir un recurso de API también puede leerlo.

| 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` con tu clave secreta, debes agregar permisos de lectura para el recurso [Customer](https://docs.stripe.com/api/customers.md) a los permisos de la RAK de reemplazo.

### 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 del servidor (p. ej., en una [bóveda de secretos](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) o una variable de entorno si tu plataforma no ofrece uno). 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

Para revisar los registros de la clave restringida en tu entorno de prueba de la [lista de claves](https://dashboard.stripe.com/apikeys), haz clic en el menú de opciones adicionales (⋯) junto a la clave y selecciona **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.
2. Selecciona **Editar clave**.
3. 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 del entorno 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 del entorno de prueba en tu entorno de preparación.

### Retirar la antigua clave secreta

Cuando estés seguro de que todo funciona en tu entorno 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 un período de seguridad durante el 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.
2. Busca la clave restringida que estás configurando.
3. Haz clic en el menú de contenido adicional (⋯) junto a la clave.
4. 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 (⋯).
2. 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(...)` → **Payment Intents: Escritura**
- `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 del entorno de prueba, como se describió anteriormente, a fin de que tu solicitud use la clave para hacer solicitudes de API Stripe. Prueba cada componente de tu solicitud que use las API de 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.

## See also

- [Claves de API](https://docs.stripe.com/keys.md)
- [Prácticas recomendadas para gestionar claves secretas de API](https://docs.stripe.com/keys-best-practices.md)
- [Lista de verificación para pasar a modo activo](https://docs.stripe.com/get-started/checklist/go-live.md)