API Keys

Las API keys controlan quién y qué puede acceder a tu servidor de Observabilidad de Failproof AI, de modo que un collector pueda enviar eventos sin obtener permisos de lectura ni de administración. Cada clave lleva uno o más permisos, y cada permiso protege rutas específicas del servidor; solo otorgas los que un trabajo necesita. La mayoría de los despliegues crean únicamente tres tipos de clave.

Las 3 claves que necesitan la mayoría de los despliegues

Clave	Permisos	Quién la usa
Clave de collector	`events:add`	El `agenteye-collector` en cada máquina agente, para enviar eventos.
Clave de lectura del dashboard	`events:read`, `keys:read`	Un operador o integración de solo lectura que consulta datos sin modificarlos.
Clave admin de bootstrap	todos los permisos	El operador que levanta la instancia por primera vez (junto con el dashboard). Se inicializa desde la variable de entorno `ADMIN_KEY`. Ver Clave admin de bootstrap.

Empieza aquí. Consulta el catálogo completo de permisos a continuación solo cuando necesites una clave con un ámbito más estrecho y personalizado. Ver también Distribución recomendada de claves y Crear claves.

Permisos

El servidor aplica un catálogo fijo de permisos; cada uno protege rutas HTTP específicas. Una clave admin los tiene todos; una clave con ámbito tiene el subconjunto que otorgues al crearla. Las cadenas de permisos desconocidas son rechazadas al crear una clave.

Nota: Dos permisos válidos son exclusivos para humanos/dashboard y no pueden asignarse a una API key: orgs:admin (administración de la instancia, exclusiva para operadores) y keys:update. Una solicitud a POST /keys o PATCH /keys/:id que intente otorgar cualquiera de los dos es rechazada con HTTP 422. Consulta la fila keys:update a continuación para entender por qué una clave bearer puede crear claves pero nunca editarlas.

Ingesta y consulta de eventos

Permiso	Rutas HTTP	Qué permite
`events:add`	`POST /events`	Ingestar lotes de eventos desde un collector. Es el único permiso que necesita un collector.
`events:read`	`GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export`	Consultar eventos, listar los entornos conocidos, listar los identificadores de modelos encontrados en los datos (usados por la vista de Modelos y los filtros de modelos), calcular el agregado de latencia que alimenta el mapa de calor / banda de percentiles, y exportar una sesión como JSONL. Los endpoints de facetas de la barra de filtros compartida `GET /events/environments` y `GET /events/agent_ids` son accesibles con `events:read` o `evaluations:read`, de modo que la página de sesiones (protegida por `evaluations:read`) reutiliza la misma faceta por organización. `GET /events/models` no es uno de ellos: requiere `events:read`, por lo que un principal que solo tenga `evaluations:read` recibirá un 403.

Sesiones y evaluaciones

Permiso	Rutas HTTP	Qué permite
`evaluations:read`	`GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs`	Listar sesiones, leer resultados de evaluaciones, el estado de salud resumido de evaluaciones usado por los dashboards, y el estado de la cola de trabajos de evaluación.
`evaluations:trigger`	`POST /sessions/:session_id/re-evaluate`	Encolar manualmente una reevaluación para una sesión finalizada.

Dashboards

Permiso	Rutas HTTP	Qué permite
`dashboards:read`	`GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles`	Listar dashboards, cargar uno y leer sus tiles.
`dashboards:write`	`POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout`	Crear y editar dashboards, agregar / editar / eliminar tiles, y reorganizar la cuadrícula de tiles.
`dashboards:delete`	`DELETE /dashboards/:id`	Eliminar un dashboard completo (la eliminación a nivel de tile corresponde a `dashboards:write`).

Consultas guardadas (compositor SQL)

Permiso	Rutas HTTP	Qué permite
`queries:read`	`GET /queries`, `GET /queries/:id`, `GET /queries/schema`	Listar consultas guardadas, cargar una e inspeccionar el esquema de solo lectura al que apunta el compositor.
`queries:write`	`POST /queries`, `PUT /queries/:id`	Crear y editar consultas guardadas. El SQL se enruta a través del mismo rol de solo lectura y las mismas verificaciones de SQL protegido que una llamada `queries:run`.
`queries:delete`	`DELETE /queries/:id`	Eliminar una consulta guardada.
`queries:run`	`POST /queries/run`	Ejecutar SQL guardado o ad-hoc contra el rol de solo lectura utilizado por el compositor.

Asistente de IA

Permiso	Rutas HTTP	Qué permite
`agent:use`	`GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages`	Interactuar con el asistente de IA y gestionar tus propias conversaciones (privadas). Requerido en el usuario para ver el panel del asistente; la clave propia del asistente es `dashboard-assistant` y se inicializa por separado (ver más abajo).

Permiso	Rutas HTTP	Qué permite
`keys:create`	`POST /keys`	Crear una nueva API key con ámbito. No otorga la capacidad de editar los permisos de una clave existente (eso es `keys:update`).
`keys:read`	`GET /keys`	Listar las claves existentes. Los secretos nunca son devueltos por este endpoint.
`keys:update`	`PATCH /keys/:id`	Editar los permisos de una clave existente. Permiso exclusivo para humanos/dashboard; no puede asignarse a una API key (una clave bearer puede crear claves pero nunca editarlas).
`keys:disable`	`POST /keys/:id/disable`	Revocar una clave. Las claves protegidas (`admin`, `dashboard-assistant`) no pueden deshabilitarse; rótalas mediante la variable de entorno y un reinicio.
`keys:regenerate`	`POST /keys/:id/regenerate`	Rotar el secreto de una clave. Las claves protegidas no pueden regenerarse mediante esta ruta.

Usuarios del dashboard

Permiso	Rutas HTTP	Qué permite
`users:create`	`POST /users`, `GET /users/defaults`	Invitar a un nuevo usuario del dashboard (emite un correo electrónico + inicio de sesión con código de un solo uso (OTP)) y leer el conjunto de permisos predeterminado configurado en el dashboard utilizado para prellenar el formulario de invitación.
`users:read`	`GET /users`, `GET /users/:id`	Listar usuarios y cargar el registro de un usuario individual.
`users:update`	`PUT /users/:id`	Editar los permisos de un usuario. Las actualizaciones envían un correo de cambio de permisos al usuario afectado y surten efecto en su siguiente solicitud; no requieren volver a iniciar sesión.
`users:delete`	`DELETE /users/:id`, `POST /users/:id/enable`	Deshabilitar un usuario (revoca sus sesiones de inmediato) y rehabilitar a un usuario previamente deshabilitado.

Estos permisos respaldan la página Users del dashboard, donde los ámbitos otorgados a cada miembro se muestran como chips:

La página Users: una tarjeta por usuario del dashboard con su email, permisos otorgados y controles de edición/deshabilitación

Configuración operacional

Permiso	Rutas HTTP	Qué permite
`settings:read`	`GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve`	Ver la configuración operacional gestionada por el dashboard y sus metadatos; listar las anulaciones de ventana de contexto por modelo; y resolver la ventana efectiva para un modelo.
`settings:write`	`PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows`	Editar la configuración operacional y agregar, cambiar o eliminar anulaciones de ventana de contexto por modelo. Los cambios afectan a los nuevos eventos sin necesidad de reiniciar el servidor.

Alertas e incidentes

Permiso	Rutas HTTP	Qué permite
`alerts:read`	`GET /alerts`, `GET /alerts/:id`	Ver las definiciones de alertas configuradas.
`alerts:write`	`POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test`	Crear, editar, eliminar y disparar alertas de prueba.
`incidents:read`	`GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers`	Ver incidentes y su historial de triaje.
`incidents:write`	`POST /alerts/:id/incidents`	Abrir un incidente manualmente contra una alerta existente.
`incidents:ack`	`POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe`	Reconocer, asignar, resolver y comentar incidentes.

Auditorías

Permiso	Rutas HTTP	Qué permite
`audits:read`	`GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid`	Ver definiciones de auditorías, historial de ejecuciones y hallazgos.
`audits:write`	`POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status`	Crear, editar, eliminar y ejecutar auditorías; triar hallazgos (reconocer / silenciar / descartar / resolver / reabrir / asignar).

Nota: Para dar a una clave acceso a la superficie de auditorías, otórgale audits:* explícitamente. Ver Notas de actualización y compatibilidad con versiones anteriores para saber cómo se migraron los titulares existentes cuando se lanzó Audits.

El endpoint del selector de destinatarios GET /alerts/recipients (que lista los emails de los miembros a los que puede notificar un editor de alertas) es accesible por un titular de alerts:read o alerts:write, de modo que los editores de alertas pueden llenar el selector sin necesitar users:read.

Un visualizador de dashboards necesita tanto dashboards:read (para cargar las vistas guardadas) como evaluations:read (las métricas de salud se calculan a partir de datos de evaluaciones). Otorga dashboards:write para que un usuario pueda crear o editar dashboards, y dashboards:delete para eliminarlos.

/health y /auth/* (solicitud OTP, verificación OTP, comprobación de sesión, cierre de sesión) no requieren autenticación por diseño; forman el flujo de inicio de sesión y la sonda de disponibilidad. GET /access-granters requiere una clave válida pero ningún permiso específico, por lo que cualquier usuario conectado puede ver qué administradores contactar sobre cambios de acceso.

Conjuntos de permisos

Los conjuntos de permisos te permiten aplicar un rol con nombre en lugar de seleccionar tokens individuales cada vez. En vez de elegir una docena de permisos uno por uno para cada nuevo usuario del dashboard o API key, eliges un conjunto, y todos los asignados a él llevan un otorgamiento consistente y revisable. Editar un conjunto personalizado vuelve a aplicar el nuevo otorgamiento a todos los usuarios ya asignados a él, de modo que un cambio de rol es una sola edición en lugar de recorrer cada miembro. Cada organización se inicializa con tres conjuntos integrados:

Conjunto	Permisos	Para quién
`read-only`	`events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read`	Acceso de solo lectura en toda la superficie operacional.
`standard`	todo lo de `read-only`, más `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use`	Solo lectura más las acciones cotidianas del operador de guardia: ejecutar consultas, reevaluar sesiones, reconocer incidentes y usar el asistente de IA.
`admin`	todos los permisos asignables	Control total de la organización.

Los tres conjuntos integrados son inmutables; sus nombres siempre significan lo mismo, por lo que read-only, standard y admin son seguros para referenciar en políticas e incorporaciones. Un operador puede crear conjuntos personalizados adicionales para modelar roles específicos de su organización (por ejemplo, un rol de “autor de dashboard” o un rol de “solo collector”). Los conjuntos están disponibles en el dashboard y se gestionan a través de la API en GET /permission-sets (listar, protegido por users:read) y POST /permission-sets / PUT /permission-sets/:name / DELETE /permission-sets/:name (crear, editar, eliminar un conjunto personalizado, protegido por settings:write). Eliminar o editar un conjunto integrado está prohibido. La pertenencia a conjuntos respalda otras dos funcionalidades:

DEFAULT_USER_PERMISSIONS (el otorgamiento preseleccionado cuando un admin abre + nuevo usuario) usa como valor predeterminado el conjunto standard.
El flag --set en agenteye-orgctl (gestión de miembros por el operador) inicia un miembro desde un conjunto con nombre, que luego puedes ajustar con --add / --remove.

Nota: Cuando un conjunto incluye un permiso que no se puede asignar a claves (por ejemplo, un conjunto personalizado que lleva keys:update), inicializar una clave desde ese conjunto descarta los tokens no asignables; de lo contrario el servidor rechazaría la clave con HTTP 422. Los usuarios del dashboard no están sujetos a esa restricción.

Clave Admin de Bootstrap

La clave admin es la credencial raíz única que permite a un operador poner en marcha el acceso desde cero: con ella puedes crear todas las demás claves con ámbito, invitar a los primeros usuarios del dashboard y configurar la instancia antes de que exista cualquier otra clave. Es la única clave que no se crea a través de la API de claves; se provisiona desde el entorno para que el servidor sea accesible en el primer arranque. Establece la variable de entorno ADMIN_KEY en el servidor. En cada inicio, el servidor hace un upsert de este valor como clave admin con todos los permisos. Para rotarla: cambia ADMIN_KEY por un nuevo secreto y reinicia el servidor.

Ámbito de organización

Las organizaciones se crean y gestionan fuera de banda por un operador, no a través de esta API de claves. El ciclo de vida de orgs y miembros (crear / renombrar / eliminar / purgar una org; agregar / actualizar / eliminar un miembro) se realiza con la CLI agenteye-orgctl; no existe una API HTTP ni un botón en el dashboard para ello. Lo que sí permanece igual: las API keys por organización se siguen creando en el dashboard (o mediante esta API de claves) por los miembros de la org. En un despliegue multi-org, cada clave que crea un miembro de una org (a través de esta API de claves o la página Keys del dashboard) pertenece a una organización y solo puede leer o escribir los datos de esa org; la org queda estampada en la clave al crearla y se aplica en cada solicitud. Las dos claves de bootstrap son la única excepción: la clave admin (inicializada desde ADMIN_KEY) y la clave dashboard-assistant (inicializada desde AGENT_API_KEY) tienen ámbito de instancia (no llevan org). El dashboard se autentica con la clave admin para poder proxiar solicitudes por organización en nombre de los miembros conectados. Los despliegues de un solo tenant no necesitan preocuparse por esto; todas las claves pertenecen a la org default integrada.

Crear claves

Usa la clave admin (o cualquier clave con permiso keys:create) para crear claves adicionales con ámbito.

Clave de collector (solo ingesta)

curl -s -X POST http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-collector",
    "key": "your-collector-secret",
    "permissions": ["events:add"]
  }'

Clave de dashboard (solo lectura)

curl -s -X POST http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dashboard",
    "key": "your-dashboard-secret",
    "permissions": ["events:read", "keys:read"]
  }'

Cuando creas una clave a través de la API HTTP, tú mismo proporcionas el valor de key; elige un secreto robusto y guárdalo de forma segura. (El dashboard funciona al revés: genera un secreto robusto por ti y lo muestra una sola vez al crearlo; ver Gestión de claves en el dashboard.) La respuesta confirma que la clave fue creada:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "prod-collector",
  "permissions": ["events:add"],
  "created_at": "2026-04-01T12:00:00Z"
}

Listar claves

curl -s http://your-server/keys \
  -H "Authorization: Bearer $ADMIN_KEY"

Los secretos de las claves no se devuelven en las respuestas de listado; solo los IDs, nombres y permisos.

Deshabilitar una clave

Deshabilitar revoca el acceso de inmediato sin eliminar el registro de la clave.

curl -s -X POST http://your-server/keys/<id>/disable \
  -H "Authorization: Bearer $ADMIN_KEY"

Regenerar una clave

Genera un nuevo secreto para una clave existente. El secreto anterior se invalida de inmediato.

curl -s -X POST http://your-server/keys/<id>/regenerate \
  -H "Authorization: Bearer $ADMIN_KEY"

La respuesta incluye el nuevo secreto en texto plano, mostrado solo una vez.

Gestión de claves en el dashboard

La página Keys del dashboard proporciona una interfaz de usuario para todas las operaciones anteriores. Necesitas una clave con permiso keys:read para ver el listado, y keys:create / keys:update / keys:disable / keys:regenerate para las acciones de crear / editar / deshabilitar / regenerar respectivamente. Editar los permisos de una clave (keys:update) es independiente de crearla (keys:create), por lo que puedes otorgar a un operador la capacidad de crear claves sin la capacidad de cambiar el ámbito de las existentes, o viceversa. La clave admin cubre todas estas acciones. Cuando creas una clave desde el dashboard no proporcionas el secreto; el dashboard genera un secreto robusto por ti y lo muestra una sola vez al crearlo. Cópialo de inmediato y guárdalo de forma segura; nunca se vuelve a mostrar, exactamente igual que con una regeneración. Puedes seguir seleccionando los permisos de la clave directamente, o inicializarlos desde un conjunto de permisos (ver más abajo).

La página API Keys: una tarjeta por clave con su nombre, permisos otorgados y fecha de creación, con acciones de regenerar y deshabilitar; las claves protegidas como admin están marcadas

Distribución recomendada de claves

Clave	Permisos	Usada por
`admin` (bootstrap mediante la variable de entorno `ADMIN_KEY`)	todos	Operaciones/configuración, y el dashboard (se autentica con `ADMIN_KEY`, proxia solicitudes de usuarios con verificaciones de permisos)
Clave de collector por host	`events:add`	Collector en cada máquina agente
`dashboard-assistant` (bootstrap mediante la variable de entorno `AGENT_API_KEY`)	`events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run`	Asistente de IA, inicializado automáticamente, protegido; no puede editarse a través de la API
Clave de telemetría del asistente (opcional)	`events:add`	Auto-instrumentación del asistente de IA, si está habilitada

Nota: La clave del asistente se inicializa automáticamente por el servidor desde la variable de entorno AGENT_API_KEY (el mismo secreto que el agente presenta como AGENTEYE_API_KEY); no hay un paso manual de creación de clave ni se involucra la clave admin. Sus permisos están fijos en el código fuente para que el ámbito no pueda ampliarse por una mala configuración: lectura sobre eventos / evaluaciones / dashboards, más escritura de dashboards y lectura / escritura / ejecución de consultas para el flujo de autoría “Pídele a la IA que escriba una consulta”. Todo el SQL sigue pasando por el mismo rol de solo lectura y la misma ruta de SQL protegido que una consulta escrita por un usuario, por lo que esto amplía la superficie de autoría, no la superficie de datos; las operaciones destructivas (queries:delete, dashboards:delete) se excluyen deliberadamente de la clave del asistente. Al igual que la clave admin, está protegida: no puede deshabilitarse ni regenerarse a través de la API de claves, solo rotarse cambiando AGENT_API_KEY y reiniciando. Los usuarios del dashboard también necesitan el permiso agent:use para ver y usar el asistente. Si habilitas la auto-instrumentación, dale al asistente una clave separada con solo events:add.

Notas de actualización y compatibilidad con versiones anteriores

Solo necesitas estas notas si estás actualizando una instancia existente; los nuevos despliegues pueden omitirlas.

Cuando se lanzó Audits, los titulares existentes fueron ampliados siguiendo las mismas formas de rol que las alertas: cada usuario y conjunto de permisos que tenía alerts:read obtuvo audits:read, y cada titular de alerts:write obtuvo audits:write. Las API keys existentes no fueron ampliadas. Otorga audits:* a una clave explícitamente si necesita acceso a la superficie de auditorías.

Los otorgamientos almacenados del token heredado alerts:ack se interpretan como incidents:ack para que los operadores de guardia conserven el acceso sin necesidad de regenerar claves. El token ya no se puede asignar desde el editor de usuarios del dashboard; la matriz ofrece incidents:ack en su lugar.

Próximos pasos

SDK de Python: cómo se autentica el código de tu agente al enviar eventos.
Seguridad: cómo funcionan el inicio de sesión, el control de acceso y el aislamiento de datos por organización.

Overview

Features

SDK and CLI

Administration

API Keys

Las 3 claves que necesitan la mayoría de los despliegues

Permisos

Ingesta y consulta de eventos

Sesiones y evaluaciones

Dashboards

Consultas guardadas (compositor SQL)

Asistente de IA

API keys

Usuarios del dashboard

Configuración operacional

Alertas e incidentes

Auditorías

Conjuntos de permisos

Clave Admin de Bootstrap

Ámbito de organización

Crear claves

Clave de collector (solo ingesta)

Clave de dashboard (solo lectura)

Listar claves

Deshabilitar una clave

Regenerar una clave

Gestión de claves en el dashboard

Distribución recomendada de claves

Notas de actualización y compatibilidad con versiones anteriores

Próximos pasos

​Las 3 claves que necesitan la mayoría de los despliegues

​Permisos

​Ingesta y consulta de eventos

​Sesiones y evaluaciones

​Dashboards

​Consultas guardadas (compositor SQL)

​Asistente de IA

​API keys

​Usuarios del dashboard

​Configuración operacional

​Alertas e incidentes

​Auditorías

​Conjuntos de permisos

​Clave Admin de Bootstrap

​Ámbito de organización

​Crear claves

​Clave de collector (solo ingesta)

​Clave de dashboard (solo lectura)

​Listar claves

​Deshabilitar una clave

​Regenerar una clave

​Gestión de claves en el dashboard

​Distribución recomendada de claves

​Notas de actualización y compatibilidad con versiones anteriores

​Próximos pasos

Las 3 claves que necesitan la mayoría de los despliegues

Permisos

Ingesta y consulta de eventos

Sesiones y evaluaciones

Dashboards

Consultas guardadas (compositor SQL)

Asistente de IA

API keys

Usuarios del dashboard

Configuración operacional

Alertas e incidentes

Auditorías

Conjuntos de permisos

Clave Admin de Bootstrap

Ámbito de organización

Crear claves

Clave de collector (solo ingesta)

Clave de dashboard (solo lectura)

Listar claves

Deshabilitar una clave

Regenerar una clave

Gestión de claves en el dashboard

Distribución recomendada de claves

Notas de actualización y compatibilidad con versiones anteriores

Próximos pasos