¿Cómo roto una clave API?

Rotar las claves API regularmente es una práctica de seguridad importante. Aquí está cómo rotar de forma segura tus claves sin interrumpir tu servicio.

¿Por qué rotar claves API?

• Mejor práctica de seguridad: Limita la exposición si una clave alguna vez se ve comprometida

• Cambios de miembros del equipo: Cuando desarrolladores se van o cambian de rol

• Sospecha de compromiso: Si crees que una clave puede haber sido expuesta

• Cumplimiento: Algunas políticas de seguridad requieren rotación periódica de claves

• Cambios de entorno: Al migrar infraestructura o refactorizar

Proceso de rotación estándar (sin tiempo de inactividad)

Paso 1: Crear una nueva clave

1. Inicia sesión en Ajustes → API

2. Haz clic en "Crear nueva clave API"

3. Nómbrala descriptivamente (ej., "Web Producción v2")

4. Copia la nueva clave inmediatamente - solo se muestra una vez

5. Almacénala de forma segura

Paso 2: Actualizar tu aplicación

• Despliega la nueva clave a tu aplicación (variables de entorno, gestor de secretos, etc.)

• Reinicia tu aplicación para cargar la nueva clave

• Verifica que la nueva clave funciona correctamente

• Monitorea por cualquier error

Paso 3: Monitorear la transición

• Mantén ambas claves activas temporalmente

• Verifica Ajustes → API para ver fechas de "Último uso"

• Espera hasta que la clave antigua no muestre actividad reciente

• Asegura que todas las instancias/servicios han cambiado a la nueva clave

Paso 4: Eliminar la clave antigua

• Una vez confirmado que la clave antigua ya no está en uso

• Elimina o desactiva la clave antigua en Ajustes → API

• Documenta la rotación para tus registros

Proceso de rotación rápida (si está comprometida)

Si una clave está definitivamente comprometida y necesitas actuar inmediatamente:

1. Elimina primero la clave comprometida en Ajustes → API

2. Crea una nueva clave de reemplazo

3. Despliega rápidamente la nueva clave a todas las aplicaciones

4. Acepta un breve tiempo de inactividad para prevenir acceso no autorizado

5. Monitorea logs de uso para cualquier actividad sospechosa

6. Contacta con soporte si es necesario

Estrategia de rotación multi-entorno

Para sistemas de producción, usa un enfoque por fases:

Semana 1: Desarrollo

• Crear y desplegar nueva clave al entorno dev

• Probar exhaustivamente

Semana 2: Staging

• Desplegar nueva clave a staging

• Ejecutar pruebas de integración

• Monitorear por problemas

Semana 3: Producción

• Desplegar nueva clave a producción durante período de bajo tráfico

• Monitorear de cerca

• Mantener clave antigua activa por 24-48 horas como respaldo

Semana 4: Limpieza

• Verificar que clave antigua no muestra actividad

• Eliminar clave antigua

• Actualizar documentación

Ejemplo de automatización

Script para ayudar a verificar que la rotación de clave está completa:

#!/bin/bash
# check-api-key.sh
OLD_KEY="sk_live_OLD123..."
NEW_KEY="sk_live_NEW789..."
echo "Probando clave antigua..."
OLD_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \
  -H "x-api-key: $OLD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}')
echo "Probando clave nueva..."
NEW_RESPONSE=$(curl -s -w "%{http_code}" -X POST https://api.cathopic.com/resources \
  -H "x-api-key: $NEW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}')
echo "Estado clave antigua: ${OLD_RESPONSE: -3}"
echo "Estado clave nueva: ${NEW_RESPONSE: -3}"
if [ "${NEW_RESPONSE: -3}" == "200" ]; then
  echo "✅ ¡La nueva clave funciona!"
else
  echo "❌ ¡La nueva clave falló!"
fi

Mejores prácticas

• Rota regularmente: Cada 90 días para claves de producción

• Documenta rotaciones: Mantén un log de cuándo se rotaron las claves y por qué

• Prueba antes de eliminar: Siempre verifica que la nueva clave funciona antes de eliminar la antigua

• Usa múltiples claves: Claves separadas por entorno facilitan la rotación

• Automatiza donde sea posible: Usa herramientas de gestión de secretos que soporten rotación automática

Lista de verificación post-rotación

Confirma estos elementos después de rotar:

• ✅ Todas las instancias de producción usando nueva clave

• ✅ Todos los entornos staging/dev actualizados (si usan la misma clave)

• ✅ Variables de entorno actualizadas

• ✅ Secretos de CI/CD actualizados

• ✅ Documentación actualizada

• ✅ Miembros del equipo notificados

• ✅ Clave antigua eliminada

• ✅ Rotación registrada para propósitos de auditoría