Una API Key es un string alfanumérico largo (típicamente 32-64 caracteres) que actúa como credencial de acceso a una API. Funciona como una contraseña: quien la posee puede hacer requests autenticados.
Apareció en los 2000s cuando las APIs web empezaron a popularizarse. Google, AWS y Stripe fueron pioneros en usarlas para controlar acceso y medir uso. Hoy son el método de autenticación más simple y común para machine-to-machine communication.
La diferencia clave con contraseñas de usuario: una API Key identifica una aplicación o servicio, no una persona. Un mismo sistema puede tener múltiples keys para diferentes entornos (desarrollo, staging, producción) o para diferentes clientes consumiendo tu API.
No confundir con JWT: un JWT es un token autofirmado que contiene datos (claims) y expira. Una API Key es opaca (no contiene información decodificable) y típicamente no expira, aunque las mejores prácticas recomiendan rotación periódica.
El flujo estándar: cuando un cliente quiere usar tu API, vos le generás una key única. El cliente la incluye en cada request, típicamente de tres formas:
- Header HTTP:
Authorization: Bearer tu_api_key_aquioX-API-Key: tu_api_key_aqui(más común y recomendado). - Query string:
GET /api/data?api_key=tu_api_key(inseguro porque las URLs se loguean en servidores y proxies). - Body en POST: menos común, similar problema de logging que query string.
Tu servidor recibe el request, extrae la key, la busca en la base de datos y verifica: ¿es válida? ¿está activa? ¿tiene permisos para este endpoint? Si todo está bien, procesás el request. Si no, devolvés 401 Unauthorized o 403 Forbidden.
Las keys se almacenan hasheadas en la base de datos (SHA-256 o bcrypt), igual que contraseñas. Solo mostrás la key en texto plano al generarla: después el usuario debe guardarla él. Si la pierde, generás una nueva.
Son ideales para APIs públicas con rate limiting: servicios como Google Maps, OpenAI, SendGrid. Cada key está asociada a un proyecto o cuenta, lo que te permite trackear uso y cobrar según consumo.
Perfectas para integraciones backend-to-backend: tu servidor llamando a un servicio externo (Stripe, AWS S3, Twilio). No hay usuario final involucrado, solo dos sistemas hablando.
Útiles en webhooks: cuando configurás que un servicio externo llame a tu API al ocurrir un evento, le das una key para que se autentique. Verificás que el request viene de quien dice ser.
No usar para aplicaciones frontend (SPAs, mobile apps): la key quedaría expuesta en el código del cliente. Cualquiera puede extraerla y abusar de tu API. Para esos casos, usá OAuth 2.0 o JWT con short-lived tokens.
No usar cuando necesitás permisos granulares por usuario. Las API Keys identifican al cliente, no al usuario final. Si tu API necesita saber quién está haciendo la acción (no solo qué app), necesitás JWT o session tokens.
Generación: usá un generador criptográficamente seguro (crypto.randomBytes(32) en Node, secrets.token_urlsafe() en Python). Nunca uses UUIDs estándar o timestamps: son predecibles.
Transmisión: HTTPS siempre. Una API Key en HTTP plano es como gritar tu contraseña en la calle. Headers, no query strings: evitan que se logueen accidentalmente.
Almacenamiento: hashea las keys en tu DB. Si te hackean la base, las keys no sirven sin el hash original. El cliente debe guardar la key en variables de entorno, nunca en código versionado.
Rotación: permite a los usuarios regenerar keys. Implementá expiración automática (30-90 días) para forzar rotación. Soporte para múltiples keys activas simultáneamente facilita rotación sin downtime.
Rate limiting: asociá límites de requests por minuto/hora a cada key. Previene abuso y ataques de fuerza bruta. Logging: registra cada uso de cada key (sin loguear la key completa, solo un identificador) para detectar uso anómalo.
Ejemplos
X-API-Key: sk_live_51H8z2KL4m9n0pQ...Authorization: Bearer gfy_1a2b3c4d5e6f7g8h9i0jcurl -H 'X-API-Key: tu_key' https://api.ejemplo.com/dataAPI_KEY=gfy_... node app.js (variable de entorno)Hash SHA-256 almacenado: 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8
Preguntas frecuentes
¿Cuál es la diferencia entre API Key y JWT?
API Key es opaca (no contiene datos), identifica una app/servicio, no expira típicamente. JWT contiene claims decodificables, identifica un usuario, expira en minutos/horas. JWT para frontend, API Key para backend.
¿Es seguro poner la API Key en el query string?
No. Las URLs se loguean en servidores, proxies, historial del navegador. Usá headers HTTP (X-API-Key o Authorization) y siempre HTTPS.
¿Cómo roto una API Key sin causar downtime?
Soporta múltiples keys activas por cliente. Genera la nueva, actualiza tus servicios para usar la nueva, y después desactiva la vieja. Ventana de 24-48hs para migrar.