01Qué es y cómo funciona
Una API key es una cadena larga de letras y números generada por un proveedor de servicios. Cuando tu aplicación realiza una solicitud a una API, incluye la key en el encabezado de la solicitud (request header) o en la cadena de consulta (query string). El servidor lee la key, la busca en su base de datos y comprueba si esa key tiene permiso para realizar la acción solicitada. Las keys pueden tener un alcance (scope) limitado para restringir qué endpoints son accesibles y cuántas solicitudes se permiten por minuto. Están vinculadas a una cuenta de facturación o a un proyecto, por lo que el uso se atribuye al propietario correspondiente. Las keys no están cifradas por defecto, por lo que deben enviarse a través de HTTPS para evitar su interceptación. No demuestran la identidad de un usuario final; demuestran la identidad de la aplicación que realiza la llamada.
Una API key es como una contraseña para las aplicaciones. La incluyes en tu solicitud y el servidor la verifica para decidir si tienes permiso para usar la API.
02Qué hacer al respecto
Esta semana, genera una nueva API key desde el panel de control de tu proveedor y guárdala en un gestor de secretos o en una variable de entorno, nunca en el código fuente. Rota cualquier key que se haya incluido en un repositorio público. Configura alertas de uso para que se te notifique si el volumen de peticiones aumenta inesperadamente. Revisa qué direcciones IP o dominios tienen permiso para usar cada key y restríngelos siempre que sea posible. Documenta qué miembros del equipo tienen acceso a qué keys y elimina el acceso de las personas que ya no lo necesiten.
03Cómo se mide o se detecta
Sabrás que una API key funciona cuando las peticiones devuelvan respuestas exitosas en lugar de errores 401 o 403. En el panel de control de tu proveedor, puedes ver el recuento de peticiones, las tasas de error y la latencia agrupadas por key. Los logs mostrarán la cadena de la key en los encabezados de las peticiones si los inspeccionas. Si una key es revocada o ha expirado, la API responderá con un error de autenticación. Las cuotas de uso suelen mostrarse por key en la sección de facturación o de uso del panel de control.
04Errores comunes
- Hardcoding de API keys directamente en el código fuente o en archivos de configuración que se suben al control de versiones
- Usar la misma key en múltiples entornos (development, staging, production) en lugar de generar keys separadas
- Dejar las keys sin restricciones para que cualquier dirección IP o dominio pueda usarlas
- No rotar las keys regularmente o después de una posible exposición
- Almacenar claves en archivos de texto plano en servidores compartidos o enviarlas a través de conexiones HTTP sin cifrar
05Límites
Las API keys no son un sustituto de la autenticación de usuarios. Identifican a la aplicación que realiza la llamada, no al usuario individual detrás de ella. Por sí solas, no proporcionan un control de acceso detallado; para ello, se necesitan tokens OAuth o autenticación basada en sesiones. Las API keys solo funcionan con servicios que las requieren explícitamente. Algunas APIs utilizan en su lugar OAuth, tokens JWT o TLS mutuo, y una API key no funcionará en esos casos. Si un servicio no expone una API, no hay ninguna clave que gestionar.
06Ejemplo práctico
Un equipo de marketing utiliza la API de OpenAI para resumir las reseñas de los clientes. Crean una clave en el dashboard de OpenAI, la asignan a su proyecto 'review-analysis' y establecen un límite de gasto mensual de $500. Su script lee la clave desde una variable de entorno llamada OPENAI_API_KEY y la incluye en el encabezado Authorization de cada solicitud. Cuando el script se ejecuta, la API devuelve los resúmenes. Si la clave se elimina o se supera el límite, la API devuelve un error y el equipo recibe una alerta por correo electrónico.La entrada anterior está escrita por GetLoopLoop. Lo que sigue es lo que los catálogos independientes recogen sobre el mismo término; nada de ello es la fuente de esta página.
- También llamado
- API key
El mismo término en Wikipedia
Catalogado en 6 idiomas07Preguntas frecuentes
¿Es una API key lo mismo que una contraseña?
No. Una API key identifica a un programa o servicio que llama a una API, mientras que una contraseña identifica a un humano que inicia sesión en una cuenta. Las API keys suelen tener permisos más amplios y permanentes, y no están diseñadas para ser memorizadas o escritas por una persona.
¿Cuándo debo usar una API key en lugar de OAuth o tokens?
Usa una API key para llamadas simples de servidor a servidor donde solo necesites identificar el proyecto que realiza la llamada, especialmente cuando el proveedor documente un flujo basado en claves. Usa OAuth o tokens de acceso de corta duración cuando necesites actuar en nombre de un usuario específico, delimitar el alcance de los permisos (scope) o permitir que los usuarios revoquen el acceso sin tener que rotar la credencial de todo el proyecto.
¿De dónde vienen las API keys y quién las emite?
Son generadas por el servicio que deseas llamar, desde la consola de desarrollador o el panel de control de ese proveedor. El proveedor vincula la clave a un proyecto o cuenta, y es tu responsabilidad crearla, copiarla y almacenarla la primera vez, ya que la mayoría de los paneles de control solo muestran el valor completo una vez.
¿Por qué mi solicitud devuelve un error 401 o 403 aunque haya enviado la clave?
Un 401 suele significar que la clave falta, es incorrecta o ha sido revocada, mientras que un 403 significa que la clave es válida pero no tiene permiso para realizar esa acción, a menudo debido a restricciones de IP, comprobaciones de referrer o un plan insuficiente. Comprueba que la clave se esté cargando desde tu gestor de secretos (secrets manager), que se envíe en el encabezado (header) que especifican las docs y que no esté alcanzando un límite de tasa (rate limit) o de cuota.
¿Qué pasa si hago un commit de una API key en el control de versiones?
Cualquier persona que encuentre el repositorio puede usar la clave como si fuera tú, lo que puede provocar el robo de cuota, facturas inesperadas o que el proveedor te revoque la clave. Rota la clave inmediatamente en el dashboard del proveedor, elimínala del historial de git y mueve las futuras claves a variables de entorno o a un gestor de secretos.
¿Las API keys caducan?
Algunos proveedores emiten claves que nunca caducan, mientras que otros requieren una rotación periódica o caducan automáticamente tras un periodo determinado. Trata cada clave como si fuera de larga duración por defecto y establece la rotación como parte de tu flujo de trabajo para que revocar una no rompa el entorno de producción.
08Preguntado en voz alta
El mismo término en las palabras que alguien usa al hablar con un asistente en lugar de escribir en un buscador: escrito desde la situación, y por eso cada pregunta lleva la situación de la que salió.
Sí, pero aun así tendrás que rotar la clave. Revócala en el dashboard de tu proveedor ahora mismo, reemplázala en tus variables de entorno o gestor de secretos y luego purga el historial de git con una herramienta como git filter-repo antes de hacer un force push. Después de eso, haz push del historial limpio e indica a tu equipo que vuelva a clonar el repositorio para que nadie conserve la clave antigua en su máquina.
Comprueba cuatro cosas en orden: que la clave sea la del proyecto correcto, que el nombre del header coincida exactamente con la documentación del proveedor, que estés llamando a la base URL del entorno al que pertenece esa clave y que no hayas alcanzado el límite de peticiones (rate limit). Si las cuatro parecen estar bien, regenera la clave una vez y haz una prueba con un curl nuevo antes de cambiar nada en el código de la aplicación.
No, genera una clave separada para ellos con el alcance (scope) más limitado que permita el proveedor, y establece una fecha de caducidad o un recordatorio en el calendario para eliminarla cuando termine el trabajo. Compartir tu clave principal vincula su uso a tu facturación y hace que la revocación sea un incidente mucho mayor si se filtra.