Uso seguro de tokens API
El token de API es una clave que concede acceso programático completo a su cuenta a través de la API REST. Si se filtra, un atacante puede hacer todo lo que usted puede hacer. Las siguientes recomendaciones reducen el riesgo de que esto le ocurra.
Trate el token como una contraseña
- Nunca incluya un token en repositorios públicos (GitHub, GitLab).
- No envíe un token por Discord, Slack o correo al depurar problemas.
- Guarde el token en una variable de entorno o en un gestor de secretos (HashiCorp Vault, AWS SSM Parameter Store, Doppler y similares).
- En la canalización de CI/CD (sistema automatizado de build/despliegue) use la función "masked secret" para que el token no aparezca en texto legible en los registros.
Rotación de tokens
En cada una de las siguientes situaciones revoque de inmediato el token antiguo y genere uno nuevo:
- Un empleado que tenía acceso se marcha.
- En el panel verá una marca de tiempo Último uso junto a cada token: si observa una actividad que no esperaba, revoque el token de inmediato.
- Al menos una vez cada 90 días como higiene rutinaria, aunque no haya pasado nada.
Un token = un propósito
No use el mismo token en cinco scripts distintos. Cree un token independiente para cada integración:
epulzio_xxxxxxxxxxxxxxxx- solo para despliegues mediante GitHub Actionsepulzio_xxxxxxxxxxxxxxxx- solo para Terraform o Pulumi (herramientas de gestión de infraestructura)epulzio_xxxxxxxxxxxxxxxx- para un panel de Grafana que descarga métricas
Si un token se filtra, solo revoca ese en concreto y las demás integraciones siguen funcionando.
Dónde guardar el token de forma segura
| Entorno | Método recomendado |
|---|---|
| CLI local | Archivo ~/.config/epulzio/token con permisos chmod 600 (solo lo lee su usuario) |
| Docker | Docker secret o --env-file (no fijo mediante ENV en el Dockerfile) |
| Kubernetes | Objeto Secret montado como variable de entorno o archivo |
| GitHub Actions | Settings -> Secrets -> EPULZIO_TOKEN |
| Funciones en la nube (AWS Lambda, GCP Functions) | AWS SSM Parameter Store o Google Secret Manager |
Token frente al secreto de firma para webhooks
Para verificar los webhooks entrantes (las notificaciones que le enviamos) use un secreto de firma (HMAC signing secret) independiente, no el token de API. Son dos cosas distintas. Encontrará los detalles en el artículo Generación de un token de API.