Claves de API

​

Permisos

No asignables a claves. Dos permisos válidos son exclusivos para humanos/panel de control y no se pueden otorgar a una clave de API: orgs:admin (administración de instancia, solo para operadores) y keys:update. Una solicitud a POST /keys o PATCH /keys/:id que intente otorgar alguno de ellos es rechazada con HTTP 422. Consulta la fila de keys:update a continuación para entender por qué una clave portadora puede crear claves pero nunca editarlas.

​

Ingesta y consulta de eventos

​

Sesiones y evaluaciones

​

Paneles de control

​

Consultas guardadas (compositor SQL)

​

Asistente de IA

​

Claves de API

​

Usuarios del panel de control

​

Configuración operacional

​

Alertas e incidentes

​

Auditorías

Cuando se lanzaron las Auditorías, los permisos de los titulares existentes se ampliaron con la misma estructura de roles que las alertas: todo usuario y conjunto de permisos que tuviera alerts:read obtuvo también audits:read, y todo titular de alerts:write obtuvo también audits:write. Las claves de API existentes no se ampliaron — otorga audits:* a una clave de forma explícita si necesita acceso a la superficie de auditorías.

Los permisos almacenados del token heredado alerts:ack se interpretan como incidents:ack, de modo que los equipos de guardia conservan el acceso sin necesidad de regenerar claves. El token ya no se puede asignar desde el editor de usuarios del panel de control; la matriz ofrece incidents:ack en su lugar.

El endpoint del selector de destinatarios GET /alerts/recipients (que lista los correos electrónicos de miembros a los que puede notificar un editor de alertas) es accesible para cualquier titular de cualquiera de los permisos alerts:read o alerts:write, de modo que los editores de alertas pueden poblar el selector sin necesitar el permiso users:read.

Un visualizador de paneles necesita tanto dashboards:read (para cargar las vistas guardadas) como evaluations:read (las métricas de salud se calculan a partir de los datos de evaluación). Otorga dashboards:write para permitir que un usuario cree o edite paneles, 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 parte del 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 autenticado puede ver qué administradores contactar sobre cambios de acceso.

​

Conjuntos de permisos

• DEFAULT_USER_PERMISSIONS (el permiso preseleccionado cuando un administrador abre + nuevo usuario) toma como valor predeterminado el conjunto standard. Consulta Implementación.
• El indicador --set en agenteye-orgctl (gestión de miembros por parte del operador) inicia un miembro desde un conjunto con nombre, que luego puedes ajustar con --add / --remove. Consulta Gestión de inquilinos.

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 elimina los tokens no asignables; de lo contrario, el servidor rechazaría la clave con HTTP 422. Los usuarios del panel de control no están sujetos a esa restricción.

​

Clave de administrador de arranque

​

Alcance por organización

​

Creación de claves

​

Clave de recolector (solo ingesta)

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

​

Clave de panel de control (solo lectura)

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

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

​

Listado de claves

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

​

Deshabilitar una clave

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

​

Regenerar una clave

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

​

Gestión de claves en el panel de control

​

Disposición recomendada de claves

Clave del asistente. 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 ningún paso manual de generación de claves ni ninguna clave de administrador involucrada. Sus permisos están fijados en el código fuente para que el alcance no pueda ampliarse por mala configuración: lectura sobre eventos / evaluaciones / paneles de control, más escritura en paneles y lectura / escritura / ejecución de consultas para el flujo de creación de consultas mediante IA. Todo el SQL sigue pasando por el mismo rol de solo lectura y las mismas comprobaciones de sql_guard que una consulta escrita por un usuario, por lo que esto amplía la superficie de creación, 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 se puede deshabilitar ni regenerar a través de la API de claves; solo se puede rotar cambiando AGENT_API_KEY y reiniciando. Los usuarios del panel de control además necesitan el permiso agent:use para ver y usar el asistente. Si habilitas la autoinstrumentación, proporciona al asistente una clave separada exclusiva para events:add.