Gestión de claves API
Las claves API son credenciales de acceso simples, pero solo resultan seguras cuando se generan, almacenan, utilizan y renuevan correctamente.
Descripción general
La gestión de claves API abarca todo el ciclo de vida de las claves: desde su generación, almacenamiento y uso hasta su rotación y revocación. Las claves API son cadenas secretas que los clientes utilizan para identificarse y, en parte, autorizarse ante una API. Son fáciles de implementar, pero entrañan riesgos si se exponen, copian o permanecen sin cambios durante largo tiempo. Una gestión adecuada genera claves fuertes y únicas, las almacena solo en forma de hash, las transmite por TLS, limita su validez y permisos, facilita su rotación y permite una revocación inmediata. Además, las claves deben configurarse con permisos mínimos y su uso debe supervisarse mediante registros y monitoreo.
Componentes clave
Generación de claves API
Las claves API deben generarse de forma criptográficamente segura y aleatoria. Deben ser lo suficientemente largas y únicas para prevenir ataques de fuerza bruta. Una longitud mínima de 32 bytes y el uso de caracteres como letras, números y símbolos especiales aumentan la seguridad. Las claves no deben ser predecibles ni basarse en datos de usuario.
Almacenamiento de claves API
En el servidor, las claves API nunca deben almacenarse en texto plano. En su lugar, guarda un hash de la clave, por ejemplo con SHA-256 o bcrypt, junto con una referencia para asociar la clave al usuario. La clave en texto plano se muestra al usuario solo una vez durante la generación. En el cliente, las claves no deben terminar en repositorios, registros ni configuraciones accesibles públicamente.
Transmisión y transporte
Las claves API siempre deben transmitirse por HTTPS. Evita incluirlas en URLs, ya que pueden aparecer en el historial del navegador, registros y encabezados referrer. El encabezado Authorization o un encabezado dedicado como X-API-Key son opciones más seguras.
Ámbitos y permisos
Las claves API deben configurarse con permisos mínimos. Una clave para acceso de solo lectura no debe permitir operaciones de escritura. Los ámbitos como read:users o write:orders ayudan a limitar los derechos y reducen el riesgo en caso de que la clave se vea comprometida.
Rotación de claves API
La rotación significa emitir nuevas claves de forma periódica o cuando se sospeche una compromisión, invalidando las antiguas. Permitir múltiples claves activas por cliente facilita la rotación, porque la clave anterior sigue funcionando mientras se distribuye la nueva. Después de un período de transición, se desactiva la clave anterior.
Revocación y desactivación
Las claves API deben poder revocarse en cualquier momento sin reiniciar todo el servicio. Una clave desactivada se rechaza en la siguiente solicitud. Los paneles de control o las APIs deben permitir bloquear rápidamente las claves si se han expuesto.
Registros y monitoreo
El uso de claves API debe registrarse. La información importante incluye marca de tiempo, dirección IP, clave utilizada, punto final y resultado. El monitoreo detecta patrones de uso inusual, como picos repentinos de tráfico, anomalías geográficas o acceso a puntos finales inusuales.
Gestión de secretos
Para aplicaciones que utilizan claves API, deben emplearse soluciones de gestión de secretos como HashiCorp Vault, AWS Secrets Manager o Azure Key Vault. Estas herramientas almacenan secretos cifrados, permiten la rotación y evitan que las claves terminen en código o configuraciones.
Comunicación de filtraciones
Si una clave API se ha expuesto, debe revocarse inmediatamente. Además, debe verificarse si se han realizado acciones fraudulentas. Los clientes y equipos internos deben ser informados y la clave debe reemplazarse.
Documentación y políticas
Las directrices claras para la generación, uso, rotación y manejo de claves API son esenciales. Los desarrolladores y clientes deben saber cómo almacenar claves de forma segura, cómo reportar filtraciones y qué consecuencias tiene incumplir las políticas.
Ejemplo práctico
Un proveedor SaaS ofrece claves API a clientes que desean acceder a la API de pedidos.
Generación de una nueva clave:
POST /api/v1/api-keys
Authorization: Bearer USER_TOKEN
Content-Type: application/json
{
"name": "Integration Warehouse",
"scopes": ["read:orders", "write:shipments"]
}Respuesta:
HTTP/1.1 201 Created
Content-Type: application/json
{
"keyId": "key-abc-123",
"key": "sk_live_51H8x...9zA2",
"scopes": ["read:orders", "write:shipments"],
"createdAt": "2026-07-01T10:00:00Z",
"expiresAt": "2027-07-01T10:00:00Z"
}La clave en texto plano se muestra solo una vez. En el servidor se almacena solo un hash de la clave. El cliente utiliza la clave:
GET /api/v1/orders
Authorization: Bearer sk_live_51H8x...9zA2Si la clave se expone, el cliente puede revocarla inmediatamente en el panel de control y generar una nueva. El permiso anterior deja de ser válido al instante.
Preguntas frecuentes: Gestión de claves API
1. ¿Qué es una clave API?
2. ¿Cómo debe generarse una clave API?
3. ¿Debe almacenarse una clave API en texto plano?
4. ¿Qué es la rotación de claves API?
5. ¿Por qué debe ser posible revocar claves API?
6. ¿Qué son los ámbitos en claves API?
7. ¿Dónde deben almacenarse las claves API en el cliente?
8. ¿Qué es una herramienta de gestión de secretos?
9. ¿Cómo detectar el uso inusual de una clave API?
10. ¿Qué ocurre cuando se filtra una clave API?
11. ¿Deben tener fecha de vencimiento las claves API?
12. ¿Cuál es la diferencia entre una clave API y un token OAuth2?
13. ¿Qué es un prefijo de clave?
14. ¿Qué es un hash en el contexto de claves API?
15. ¿Por qué las claves API no deben estar en URLs?
Fuentes
- https://owasp.org/API-Security/editions/2023/en/0x11-t10/
- https://cheatsheetseries.owasp.org/cheatsheets/Key_Management_Cheat_Sheet.html
- https://www.vaultproject.io/
Recomendaciones de libros sobre seguridad en APIs
Si quieres profundizar en gestión de claves API, Secret Management y seguridad en APIs, te recomendamos los siguientes libros:
Keine Bücher für Kategorie "security" gefunden.