Qué es una clave de API: definición, uso y seguridad

¿Qué es una clave de API?

Una clave de API (API key) es una cadena secreta que identifica a la aplicación o al usuario que llama a una API. El servidor la busca en cada petición para decidir quién llama, qué límites se aplican y qué se factura. Es la forma más simple de autenticación de una API, pero es un único secreto compartido: quien tiene la clave puede actuar como su propietario.

Cómo funciona una clave de API

El proveedor genera una clave larga y aleatoria y la muestra una sola vez. El cliente la guarda y la envía con cada petición, normalmente en una cabecera. El servidor la compara con lo que tiene almacenado y permite, limita o rechaza la llamada.

GET /v1/orders HTTP/1.1
Host: api.example.com
X-API-Key: sk_live_EXAMPLE_NOT_A_REAL_KEY

La guía de seguridad REST de OWASP indica que las claves de API y los tokens no deben aparecer en la URL, porque pueden quedar registrados en los logs del servidor web.

Generar y guardar claves

Trata una clave como una contraseña. Genérala con una fuente aleatoria criptográficamente segura, muéstrala al usuario una sola vez y guarda en el servidor solo un hash. Un hash rápido como SHA-256 basta para una clave larga y aleatoria, y aunque se filtre tu base de datos el atacante no puede usar las claves.

import crypto from 'crypto';

const key = 'sk_live_' + crypto.randomBytes(24).toString('hex');
const hash = crypto.createHash('sha256').update(key).digest('hex');

// show `key` to the user once, store only `hash` in the database
await db.apiKeys.insert({ userId, keyHash: hash });

Clave de API frente a OAuth y JWT

Una clave de API identifica una aplicación, no a una persona, y rara vez caduca por sí sola. Por eso OWASP advierte de no depender únicamente de las claves de API para proteger recursos sensibles o de gran valor.

Buenas prácticas de seguridad para claves de API

• Mantén las claves en secreto. No las subas a git, no las pegues en tickets ni las captures en pantalla. Cárgalas desde variables de entorno o un gestor de secretos.
• Usa claves distintas por entorno y por integración, para que una fuga tenga poco alcance.
• Da a cada clave el mínimo privilegio necesario, por ejemplo solo lectura.
• Restringe dónde funciona con una lista de IP permitidas o de orígenes permitidos, si el proveedor lo admite.
• Rota con una periodicidad y ante cualquier sospecha. Emite la clave nueva, acepta ambas durante un breve solapamiento, migra los clientes y revoca la antigua.
• Limita y registra el uso por clave para que el abuso y las fugas se vean como anomalías. Véase abuso de API.
• Usa siempre HTTPS, para que la clave vaya protegida en tránsito.

Errores habituales con las claves de API

• Incrustar una clave de servidor en JavaScript del frontend o en una app móvil, donde cualquiera puede extraerla.
• Dejar una clave en el historial de git. Borrar el archivo no la elimina: rota la clave.
• Enviar claves en las URL, que proxies, navegadores y herramientas de analítica registran.
• Usar una única clave todopoderosa para todos los servicios y entornos.
• Guardar las claves en claro en la base de datos en vez de sus hashes.
• Compartir claves por chat o correo en lugar de usar una caja fuerte de secretos.

Probar y monitorizar APIs que usan claves

Las claves condicionan cómo pruebas una API. Usa una clave de prueba específica, a ser posible contra un entorno de staging, para que una prueba de carga no consuma una cuota de producción ni active el límite de un cliente real. Si el proveedor limita las peticiones por clave, una sola clave alcanzará ese límite mucho antes que tus servidores, así que comprueba antes cuál es. El artículo sobre las causas habituales del rate limiting en APIs lo trata, y cómo hacer pruebas de carga de APIs REST con LoadFocus explica una primera ejecución (ambos en inglés).

Puedes añadir la cabecera de la clave a una petición puntual con la herramienta curl en línea gratuita, y a comprobaciones programadas con la monitorización de APIs de LoadFocus, que admite cabeceras personalizadas y ejecuta comprobaciones cada 5 minutos en el plan gratuito. Sobre los endpoints que desbloquea una clave, véase endpoint de API, y para el panorama completo seguridad de APIs.

Preguntas frecuentes sobre claves de API

¿Son seguras las claves de API?

Son más débiles que OAuth 2.0 o el TLS mutuo, porque un solo secreto es toda la prueba. Son aceptables para usos de bajo riesgo entre servidores si se combinan con HTTPS, permisos acotados, límites de uso y rotación.

¿Qué diferencia hay entre una clave de API y un bearer token?

Una clave de API identifica una aplicación y suele valer hasta que la rotas. Un bearer token es una credencial, a menudo de vida corta y ligada a un usuario y un scope, emitida mediante un flujo como OAuth 2.0. Muchas APIs aceptan ambos en la misma cabecera.

¿Cómo roto una clave de API?

Crea una clave nueva, haz que la API acepte ambas durante un periodo de transición, cambia todos los clientes a la nueva y revoca después la antigua.

¿Dónde debo guardar las claves de API?

En un gestor de secretos o en variables de entorno del servidor, nunca en el código fuente ni en una app cliente. Del lado del proveedor, guarda solo un hash.

¿Puedo usar una clave de API en una app móvil?

Se puede extraer del binario de la app, así que considérala pública. Restríngela todo lo que permita el proveedor, o haz las llamadas a través de tu propio backend y guarda allí la clave real.

¿Cómo detecto una clave de API filtrada?

Ejecuta un escáner de secretos como GitHub secret scanning o gitleaks sobre tus repositorios y su historial, y vigila el uso por clave en busca de volúmenes o ubicaciones inusuales. Rota cualquier clave filtrada.