Veille

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

CampoDescripción
NombreEtiqueta única por cuenta (el alias en algunos mensajes de error). Aparece en el registro de solicitudes y en los filtros de análisis.
CategoríaEtiqueta de organización (véase Categorías). No tiene efecto en el comportamiento de la API.
ActivoActiva o desactiva la clave. Las claves inactivas se rechazan inmediatamente con 401 Inactive API Key.
ExpiraFecha opcional tras la cual la clave deja de funcionar. Deje en blanco para no tener expiración.
Límites de solicitudesLí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íaUso típico
productionTráfico en vivo, sistemas orientados al cliente
developmentDesarrollo local y pruebas
stagingEntornos de preproducción y CI
PersonalizadaCualquier 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):

CuotaVentana
TotalLímite global estricto en el panel de control. Histórico: la clave se bloquea permanentemente una vez alcanzado
DiariaLímite en ventana deslizante de 24h. Últimas 24 horas (deslizante, no de medianoche a medianoche)
SemanalLímite en ventana deslizante de 7d. Últimos 7 días (deslizante)
MensualLí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:

CampoDescripción
EndpointMétodo HTTP y ruta
EstadoCódigo de estado de la respuesta
DuraciónTiempo hasta el primer byte (ms)
IPDirección IP del llamante
CréditosCré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ónEfecto
DesactivarEdite 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.
ArchivarDesde 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.
EliminarDesde 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

ErrorEstadoCausa
Invalid API Key401Clave no encontrada o malformada
Inactive API Key401Clave desactivada
Expired API Key401La clave ha superado su fecha de expiración
Rate limit exceeded for the API key: quota …401Cuota deslizante por clave alcanzada
Rate limit exceeded: You've exceeded the … rate limit on your subscription401Límite por segundo o por minuto a nivel de plan
IP temporarily blocked403Demasiados 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.

En esta página