AiHummer
Español▾
Iniciar sesiónCuenta
v1.0.x▾
v1.2.xstablev1.1.xstablev1.0.xstable
{ }Swagger
Seguridad/RBAC y claves API con alcance

RBAC y claves API con alcance

v1.0.x · actualizada 2026-07-07

AiHummer protege su superficie de administración con control de acceso basado en roles y claves de API con alcance. Los roles deciden quién se le permite ser a una persona; las claves con alcance permiten dar a una pieza de automatización solo los privilegios que realmente necesita, en lugar de una clave que pueda hacer todo.

Roles

El acceso a la API de administración y a la interfaz de administración está regido por roles. Un rol determina qué grupos de recursos puede ver un principal y cuáles puede modificar.

Los roles se gestionan en las interfaces de administración Roles página. Fuera de la caja hay roles integrados — owner (todo), admin, operator y member — que son de solo lectura (marcados con una insignia de “Integrado”; no se pueden editar ni eliminar). Más allá de esos, puedes crear roles personalizados: el formulario de rol toma un nombre, una descripción y una cuadrícula de permisos — casillas de verificación de lectura/escritura para cada uno de los ~19 dominios de recursos (agentes, conversaciones, herramientas, secretos, complementos, configuraciones, aprobaciones, claves de API, y así sucesivamente; “escribir” implica automáticamente “leer”). Cada rol muestra cuántos sujetos lo usan; un rol que está asignado a alguien no puede ser eliminado hasta que se eliminen las asignaciones.

Combina roles con los otros controles en este sitio — Lista de permitidos de IP, SSO empresarial y el registro de auditoría — para que cada acción administrativa esté tanto autorizada como registrada.

Claves API con alcance

Las claves API llevan ámbitos que limitan lo que la clave puede hacer. Los alcances definidos son:

Alcance Subvenciones
chat El endpoint compatible con OpenAI para el usuario final (el predeterminado antiguo para las claves existentes).
admin:read Acceso de solo lectura a los recursos de administrador (GET /v1/admin/*: ajustes, conversaciones, análisis, etc.).
admin:write Llamadas a la API de administración que mutan (POST/PUT/DELETE /v1/admin/*).
mcp El endpoint MCP publicado (POST /v1/mcp).
a2a El endpoint publicado de Agente a Agente (POST /a2a/message).
* Acceso completo a todo (el verdadero alcance de acceso completo).

Además, un genérico <area>:* comodín funciona: admin:*, por ejemplo, subvenciones cada acción de administrador pero sí no conceder chat, mcp o a2a — no es un ámbito definido por separado, solo es un caso del comodín. Solo * otorga acceso completo a todas las superficies.

Las claves emitidas antes de que existieran los ámbitos siguen funcionando sin restricciones; se pueden emitir nuevas claves con un ámbito restringido de manera que, por ejemplo, un panel que solo lee métricas nunca tenga una clave que pudiera cambiar configuraciones.

[!TIP] Aplicar el principio de privilegios mínimos: una integración de monitoreo o informes debería obtener un admin:read llave, no admin:write — y mucho menos *. Reservar * para llaves que realmente necesitan acceso a cada superficie.

Elegir el alcance adecuado

  • Clientes de chat (llamando al endpoint compatible con OpenAI) → chat.
  • Integraciones de solo lectura (tableros, exportadores, verificaciones de estado) → admin:read.
  • Automatización que crea o edita recursos (agentes de aprovisionamiento, importación conocimiento, gestión de horarios) → admin:write.
  • Clientes de MCP y A2A → mcp y a2a respectivamente.
  • Romper vidrio / acceso completo → *, sostenido por la menor cantidad de teclas posible y rotado regularmente.

[!WARNING] Una clave con alcance sigue siendo una credencial para la API de administración. Guárdela en el bóveda de secretos o tu propio gestor de secretos, nunca en control de la fuente, y gírelo si puede haber estado expuesto.

Cómo se gestionan las llaves

Las claves de la API de administrador se gestionan a través de la API de administrador (/v1/admin/apikeys) y la interfaz de administración, donde se crea una clave, se asigna su alcance y se revoca cuando ya no es necesaria. Porque la propia API de administración está protegida por OIDC y la lista de permitidos de IP, acuñar una clave es una operación autenticada y auditada.

¿A dónde vamos ahora?