Claves API
Cree, configure y gestione claves API desde su panel de control.
Las claves API autentican sus solicitudes a la API. Las gestiona completamente desde API → Claves API en el panel de control: establezca una categoría, restrinja el uso con cuotas deslizantes, añada una fecha de expiración y monitorice la actividad por clave en el registro de solicitudes.
Para saber cómo incluir una clave en una solicitud, consulte la Introducción.
Crear una clave
Abrir el formulario
Vaya a API → Claves API en su panel de control y haga clic en Nueva clave API.
Completar los campos
Asigne a la clave un Nombre (único en la cuenta), elija una Categoría en la pestaña Opciones de clave API y, opcionalmente, defina Expira y los Límites de solicitudes.
Copiar el secreto
Haga clic en Crear clave API. La ventana Clave API creada muestra la clave completa con un botón Copiar: guárdela de inmediato en una variable de entorno o en un gestor de secretos.
Campos de la clave
| Campo | Descripción |
|---|---|
| Nombre | Etiqueta única por cuenta (el alias en algunos mensajes de error). Aparece en el registro de solicitudes y en los filtros de análisis. |
| Categoría | Etiqueta de organización (véase Categorías). No tiene efecto en el comportamiento de la API. |
| Activo | Activa o desactiva la clave. Las claves inactivas se rechazan inmediatamente con 401 Inactive API Key. |
| Expira | Fecha opcional tras la cual la clave deja de funcionar. Deje en blanco para no tener expiración. |
| Límites de solicitudes | Límites opcionales por clave en ventanas deslizantes (véase Cuotas por clave). |
Categorías
Las categorías etiquetan las claves para su organización. Aparecen en los filtros y análisis del panel de control pero no cambian cómo la API procesa una solicitud.
| Categoría | Uso típico |
|---|---|
production | Tráfico en vivo, sistemas orientados al cliente |
development | Desarrollo local y pruebas |
staging | Entornos de preproducción y CI |
| Personalizada | Cualquier etiqueta libre, p. ej. sandbox, partner-acme |
Mantenga una clave por entorno para poder revocarla o rotarla de forma independiente.
Cuotas por clave
Cada clave puede tener límites máximos independientes sobre el volumen de solicitudes, aplicados en ventanas deslizantes (no límites de calendario):
| Cuota | Ventana |
|---|---|
| Total | Límite global estricto en el panel de control. Histórico: la clave se bloquea permanentemente una vez alcanzado |
| Diaria | Límite en ventana deslizante de 24h. Últimas 24 horas (deslizante, no de medianoche a medianoche) |
| Semanal | Límite en ventana deslizante de 7d. Últimos 7 días (deslizante) |
| Mensual | Límite en ventana deslizante de 30d. Últimos 30 días (deslizante) |
Deje un campo en blanco para no aplicar límite para esa ventana. Cuando se alcanza una cuota, la API devuelve 401 con Rate limit exceeded for the API key: y el nombre de la cuota en el mensaje:
{ "error": "Rate limit exceeded for the API key: quota total" }Los contadores de cuota se agregan desde los registros de solicitudes y se almacenan en caché hasta 24 horas. La aplicación es precisa dentro de esa ventana, no a la solicitud exacta.
Las cuotas por clave son distintas de los límites de tasa a nivel de plan (límites por segundo y por minuto que se aplican a toda la cuenta). Ambos devuelven 401, con un mensaje que indica el límite alcanzado. Consulte Gestión de errores para más detalles.
Expiración
Establezca una fecha de expiración en claves usadas en scripts, pipelines de CI o integraciones con socios. Una vez superada la fecha, la API devuelve:
{ "error": "Expired API Key" }Código de estado HTTP 401. Cree y despliegue una clave de reemplazo antes de la fecha de expiración para evitar interrupciones.
Registros de solicitudes
Cada solicitud realizada con una clave queda registrada en API → Request log en el panel de control, donde puede filtrar por Clave API. Cada entrada muestra:
| Campo | Descripción |
|---|---|
| Endpoint | Método HTTP y ruta |
| Estado | Código de estado de la respuesta |
| Duración | Tiempo hasta el primer byte (ms) |
| IP | Dirección IP del llamante |
| Créditos | Créditos cobrados por esta solicitud |
Use los registros para auditar la actividad por clave, depurar errores inesperados o identificar tráfico de claves comprometidas.
Desactivar, archivar o eliminar
| Acción | Efecto |
|---|---|
| Desactivar | Edite la clave y ponga Activo en No. La clave se bloquea de inmediato y permanece en la lista. Vuelva a activarla para usarla otra vez. |
| Archivar | Desde el menú de la fila. La clave se bloquea y se oculta de la lista. Archivadas permite verla. Restaurar la devuelve a la lista, todavía inactiva. El alias sigue reservado. Se conserva el historial de peticiones. |
| Eliminar | Desde la ventana de edición. Elimina permanentemente la clave y su configuración. Solo es posible si la clave nunca ha sido usada. |
Archive una clave ya usada cuando deba salir de la lista. Desactívela si piensa reactivarla pronto. Una clave con historial de peticiones no se puede eliminar. El historial se conserva para la facturación y la auditoría.
Rotación de una clave
Crear la clave de reemplazo
Vaya a API → Claves API en su panel de control, haga clic en Nueva clave API y asígnele la misma categoría y los mismos límites de solicitudes con un nombre nuevo.
Desplegar la nueva clave
Actualice la variable de entorno en cada sistema que use la clave antigua y vuelva a desplegar.
Desactivar la clave antigua
Establezca la clave antigua como inactiva, o archívela para ocultarla de la lista. Esto bloquea las solicitudes restantes sin eliminar su historial.
Referencia de errores
| Error | Estado | Causa |
|---|---|---|
Invalid API Key | 401 | Clave no encontrada o malformada |
Inactive API Key | 401 | Clave desactivada |
Expired API Key | 401 | La clave ha superado su fecha de expiración |
Rate limit exceeded for the API key: quota … | 401 | Cuota deslizante por clave alcanzada |
Rate limit exceeded: You've exceeded the … rate limit on your subscription | 401 | Límite por segundo o por minuto a nivel de plan |
IP temporarily blocked | 403 | Demasiados intentos de autenticación fallidos desde la misma IP |
Véase también: Buenas prácticas para directrices de seguridad y Glosario para definiciones de términos.