Toda integración con Stripe empieza con la misma pregunta: ¿qué clave va en cada sitio? Stripe te entrega una clave publicable, una clave secreta y la opción de generar claves restringidas, cada una en versión de prueba y de producción. Si pones la equivocada en el lugar equivocado, o filtras la capacidad de mover dinero o pierdes una tarde entera con un 401. Esta guía explica qué hace cada clave de API de Stripe, dónde se guarda, cómo enviar una primera solicitud en modo de prueba y cómo mantener la clave de producción fuera de cualquier cosa que compartas. Si quieres primero el concepto general, empieza por qué es una clave de API. Todo lo que sigue se basa en la documentación de claves de API de Stripe, revisada en septiembre de 2026.
Dónde están tus claves de API de Stripe en el Dashboard
Abre la página de claves de API en dashboard.stripe.com/apikeys. Se encuentra en Developers dentro del Dashboard y muestra las claves de la cuenta o del sandbox que estés viendo. Un conmutador alterna entre el modo sandbox y el modo live, y la lista de claves cambia con él.
La página tiene dos listas:
- Claves estándar: contienen tu clave publicable y tu clave secreta.
- Claves restringidas: contienen las claves que hayas creado con permisos delimitados.
La visibilidad cambia según el modo. En un sandbox puedes revelar cualquier clave en cualquier momento. En modo live, una clave secreta que crees tú mismo se muestra una sola vez, en el momento de crearla. Cópiala en tu gestor de secretos antes de cerrar el diálogo; si la pierdes, tendrás que rotarla. En modo live solo se pueden volver a revelar las claves predeterminadas que generó Stripe.
Hay algo que la página no muestra: los secretos de firma de webhooks. Esos están en Webhooks, uno por endpoint, y no son claves de API en absoluto.
Claves publicables frente a claves secretas
Los nombres describen el límite de confianza.
| Clave | Prefijo | Seguro exponerla | Qué puede hacer |
|---|---|---|---|
| Publicable | pk_test_ / pk_live_ |
Sí | Identificar tu cuenta y crear tokens y PaymentMethods a partir de los datos de la tarjeta en Stripe.js, Elements y los SDK móviles |
| Secreta | sk_test_ / sk_live_ |
No | Todo: crear cargos, emitir reembolsos, leer datos de clientes, desencadenar pagos |
| Restringida | rk_test_ / rk_live_ |
No | Solo los recursos y permisos que concedas |
Una clave publicable va en el navegador o en la app móvil. Convierte un número de tarjeta en un token y poco más. No puede crear un cargo ni leer datos de la cuenta, así que es normal incluirla en el código del frontend.
Una clave secreta va en tu servidor y en ningún otro sitio. La recomendación de Stripe ha cambiado: ahora la documentación dice que «no recomiendan usar claves secretas para casos de uso nuevos» y remite a las claves restringidas. La clave secreta sin restricciones sigue funcionando, pero trátala como un recurso de emergencia, no como la opción predeterminada.
Claves de modo de prueba y de modo live
Stripe gestiona dos mundos separados, cada uno con su propio conjunto de claves. Las claves de prueba (la documentación más reciente llama «sandbox» al lado de pruebas, aunque los prefijos siguen diciendo _test_) devuelven objetos simulados: clientes falsos, PaymentIntents falsos, tarjetas de prueba que se aprueban o se rechazan a voluntad, y nada de dinero real. Las claves live llegan a las redes de tarjetas y mueven fondos reales.
La separación es estricta. Un cliente creado con sk_test_ no existe para sk_live_, y viceversa. El código de error de Stripe para mezclar los flujos, livemode_mismatch, lo dice sin rodeos: “Test and live mode API keys, requests, and objects are only available within the corresponding mode.”
De ahí se derivan dos reglas prácticas:
- Desarrolla y prueba todo contra
sk_test_ork_test_. Stripe recomienda un sandbox general separado para las integraciones nuevas, de modo que su configuración y sus datos permanezcan aislados. - Pasar a live es un cambio de configuración, no de código. Tu servidor lee la clave de una variable de entorno o de un gestor de secretos, y pasar a producción significa cambiar ese valor.
Todas las respuestas de la API incluyen un booleano livemode. Comprueba su valor en tus tests; es la protección más barata contra un despliegue con la clave equivocada.
Claves restringidas y mínimo privilegio
Una clave de API restringida (Stripe la abrevia como RAK) es una clave secreta con una máscara de permisos. Cuando creas una, eliges un permiso para cada grupo de recursos: None, Read o Write. Todo viene por defecto en None. Write incluye Read, y la correspondencia con HTTP es sencilla: GET necesita Read, y POST y DELETE necesitan Write.
Para crear una, haz clic en Create restricted key en la página de claves de API, elige un conjunto de permisos preconfigurado o empieza desde cero, ponle un nombre, define los permisos y completa la solicitud de doble factor. Igual que con una clave secreta creada por ti en modo live, el valor solo se muestra una vez.
La guía de claves restringidas sugiere una clave por servicio: un servicio de facturación recibe Write en Invoices y Customers, y una tarea de informes recibe Read en Charges y Disputes. Si un servicio se ve comprometido, el atacante queda encajonado en los permisos de esa clave. Una clave de solo lectura de disputas no puede crear un cargo ni tocar un pago.
Da permisos amplios a una clave nueva en un sandbox, ejecuta tu batería de tests y después abre los registros de solicitudes de la clave (menú de opciones, View request logs) y recorta todos los permisos que no hayan recibido tráfico. Stripe también permite etiquetar las claves destinadas a agentes de IA autónomos para que queden sujetas a reglas de aprobación de pagos y reembolsos; usa esa vía en lugar de una clave secreta simple.
Tu primera solicitud con curl y Python
Stripe se autentica con HTTP Basic Auth: la clave es el nombre de usuario y la contraseña está vacía. Los dos puntos finales indican a curl que no pregunte:
export STRIPE_API_KEY=sk_test_... # your sandbox secret key
curl https://api.stripe.com/v1/payment_intents \
-u "$STRIPE_API_KEY:" \
-d amount=2000 \
-d currency=usd \
-d "automatic_payment_methods[enabled]=true"
La respuesta es un PaymentIntent con un id que empieza por pi_, status: "requires_payment_method" y livemode: false. Ese último campo confirma que usaste una clave de prueba.
Stripe también acepta -H "Authorization: Bearer $STRIPE_API_KEY", que es la forma que usan Apidog y la mayoría de los clientes HTTP. Ambas transportan la misma clave; si no tienes claro qué estilo encaja con tu stack, nuestra comparativa de claves de API y tokens bearer repasa las ventajas y desventajas. Las solicitudes deben ir por HTTPS; con HTTP simple fallan sin más, según la referencia de autenticación.
En Python, el patrón actual del SDK es un StripeClient que lee la clave del entorno:
import os
import stripe
client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])
intent = client.v1.payment_intents.create({
"amount": 2000,
"currency": "usd",
"automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode) # pi_..., False
En el archivo no aparece ninguna cadena de clave. El mismo código se ejecuta contra prueba o live según lo que proporcione el entorno.
Deja que tu agente de código pruebe la clave de Stripe con Apidog CLI
Curl demuestra una vez que la clave funciona. Tu agente de código puede convertir eso en una comprobación repetible mediante Apidog CLI y mantener la clave fuera del proyecto compartido. Configúralo una vez (el token está en Account Settings, API Access Token):
npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com # pick your agent when prompted
Después dale al agente un único prompt:
Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.
Los comandos que ejecuta, comprobados con Apidog CLI 2.2.7:
apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
--env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json
El prompt especifica la codificación de formulario porque los endpoints v1 de Stripe no aceptan JSON. La aserción sobre livemode es tu alarma: si alguien ejecuta el caso con una clave live, falla antes de que salga una segunda solicitud. En CI, la misma línea de apidog run lee la clave del almacén de secretos de tu pipeline; nuestra guía sobre pipelines de CI/CD con Apidog CLI tiene una versión lista para copiar y pegar. La definición de la solicitud se comparte; la credencial live, nunca.
Rotar claves y qué hacer si se filtra una
La propia guía de gestión de claves de Stripe es tajante: da por comprometido todo lo que se haya confirmado en un repositorio, pegado en un chat o impreso en un log, aunque no tengas la certeza de que alguien lo haya visto.
La rotación está integrada en el Dashboard. En el menú de opciones de una clave, elige Rotate key, establece una caducidad para la clave antigua y copia la de reemplazo. Ambas funcionan durante el periodo de gracia, de hasta 7 días, así que puedes desplegar de forma gradual y vigilar los registros de solicitudes en busca de rezagados. Now revoca la clave antigua de inmediato.
Si se filtra una clave secreta o restringida:
- Rótala de inmediato con una caducidad corta.
- Actualiza todos los servidores que la usaban, confirma el tráfico en los registros de solicitudes y deja que la clave antigua caduque.
- Revisa la actividad reciente en Workbench buscando cualquier cosa que tu integración no haría: cuentas conectadas no reconocidas, pagos que no iniciaste, cuentas bancarias nuevas.
- Pausa los pagos sospechosos, revierte los que ya se hayan enviado y reembolsa rápido los cargos fraudulentos para anticiparte a las disputas.
- Rota también tus demás claves. Si una se filtró, supón que el canal por el que se filtró vio más.
Stripe escanea en busca de claves expuestas y te avisará, a veces desactivando la clave de forma proactiva, pero la detección no está garantizada. Buscar sk_live_ y rk_live_ en tus repositorios y en la configuración de CI es una auditoría de cinco minutos, y un escáner de secretos en un hook de pre-commit evita que la siguiente se cuele. Stripe nunca te pide tu clave secreta, así que cualquier mensaje que la solicite es phishing.
Errores habituales con las claves de API de Stripe
| Síntoma | Qué significa | Solución |
|---|---|---|
401 “No valid API key provided” |
Clave ausente, mal formada o revocada | Revisa la cabecera; confirma que la clave no se haya rotado |
api_key_expired |
La clave se rotó o caducó | Obtén la clave actual del Dashboard |
secret_key_required |
Enviaste una clave pk_ a un endpoint del lado del servidor |
Usa sk_ o rk_ en el backend |
resource_missing en un id que sabes que existe |
Modo equivocado: clave de prueba contra un objeto live, o al revés | Haz coincidir el modo de la clave con el del objeto |
403 “doesn’t have permissions to perform the request” |
La clave restringida no tiene Read o Write en ese recurso | Edita los permisos de la clave; el cuerpo del error indica qué falta |
livemode_mismatch |
Mezclar claves u objetos de prueba y live en una misma solicitud | Mantén cada entorno completamente en un solo modo |
Los casos 401 y 403 se corresponden con stripe.AuthenticationError y stripe.PermissionError en el SDK de Python, según la referencia de errores, así que puedes capturarlos de forma específica. Un caso menos evidente: una clave live que no ha creado transferencias ni pagos en 180 días queda limitada para esas acciones, con una opción Restore access en la clave.
Preguntas frecuentes
¿Es seguro poner una clave publicable de Stripe en el código de mi frontend?
Sí. Una clave pk_ tokeniza los datos de la tarjeta, pero no puede crear cargos, leer clientes ni mover dinero. Solo las claves secretas y restringidas permanecen en el servidor.
¿Puedo usar una clave restringida en modo de prueba?
Sí. Las claves restringidas existen en ambos modos (rk_test_ y rk_live_). Stripe recomienda ajustar primero la versión de prueba y después crear una clave live con permisos equivalentes.
¿El secreto de firma de webhooks es lo mismo que mi clave de API?
No. Los secretos de firma se emiten por cada endpoint de webhook y solo sirven para verificar que un evento entrante proviene de Stripe. Están en Webhooks, no en la página de claves de API. Si estás configurando eso, mira cómo probar webhooks de Stripe en CI.
¿Qué pasa si uso una clave de prueba en producción?
Las solicitudes se completan, pero no se cobra ninguna tarjeta ni se mueve dinero. Como livemode devuelve false en todos los objetos, una aserción sobre ese campo detecta el error antes que los clientes.
En resumen
Las claves publicables van en el cliente, las secretas y las restringidas se quedan en el servidor, prueba y live nunca se mezclan, y las restringidas son mejores que las secretas siempre que puedas delimitar sus permisos. Guarda la clave live en un gestor de secretos, pasa la clave de prueba a Apidog CLI en tiempo de ejecución y mantén una aserción de livemode en cada caso de prueba que escriba tu agente.