Management Authentication (Español)

Matrices de ámbitos

Los ámbitos de administración de claves de API y los ámbitos de tokens de acceso utilizan vocabularios diferentes. Los ámbitos de herramientas MCP constituyen un tercer vocabulario, que se comprueba con scopeMatches en lugar de cualquiera de las funciones de las tablas siguientes. Comparación en paralelo: Tres espacios de nombres de ámbitos.

Ámbitos de tokens de acceso (oma_live_…)

Ámbito	Operaciones habituales
read	Solicitudes GET de listado/estado que el token tiene permitido consultar
write	Modificaciones (crear/actualizar/eliminar) por debajo del nivel de administrador
admin	CLI remota completa / token de conexión (el arranque con contraseña usa este valor de forma predeterminada)

Un token con read no puede llamar a una ruta write. Formato del mensaje en tiempo de ejecución: Access token scope '<have>' is insufficient; '<need>' required.

Ámbitos de administración de claves de API

Ámbito	Significado
(ninguno)	Solo inferencia. Las rutas de administración devuelven 403.
manage	API de administración (misma validación que la rama de clave de API de requireManagementAuth)
admin	También satisface hasManageScope (se considera con capacidad de administración)

Habilita manage en la clave desde la interfaz de usuario de API Keys / API Manager. No reutilices una clave de cliente de chat para automatización, a menos que hayas concedido deliberadamente ese ámbito.

---

Cómo crear y revocar

Sesión JWT del panel

1. Abra /login e inicie sesión con la contraseña de administración (INITIAL_PASSWORD en el primer arranque).
2. La cookie auth_token es HttpOnly. El panel web la utiliza automáticamente.
3. Cierre sesión mediante /api/auth/logout. No hay ningún secreto de larga duración que copiar.

Token de ID de máquina de la CLI

1. Ejecute omniroute en el mismo host que el servidor (bucle local).
2. La CLI inicializa un token de ID de máquina en ~/.omniroute/ (chmod 600).
3. Esto no funciona desde otra máquina. Utilice un token de acceso para una CLI remota.

Token de acceso con ámbito (oma_live_…)

1. Panel: Configuración → Tokens de acceso → crear (nombre + ámbito). El secreto se muestra una sola vez.
2. O mediante la CLI: omniroute connect <host> (contraseña → token). Consulte Modo remoto.
3. Encabezado: Authorization: Bearer oma_live_…
4. Revóquelo desde la misma página de Tokens de acceso (o elimine el contexto de la CLI).
5. El servidor solo almacena un hash. Trate el texto sin formato como una contraseña.

Clave de API con ámbito de administración

1. Panel: Administrador de API / Claves de API → cree o edite una clave → habilite manage (o admin).
2. Encabezado: Authorization: Bearer sk-… (el prefijo real de la clave).
3. Revóquela o elimine manage desde la misma interfaz.
4. Principio de mínimo privilegio para automatizaciones que no utilicen la CLI: prefiera un token de acceso read para tareas que solo realicen solicitudes GET; utilice manage en una clave de API únicamente cuando el cliente también deba comunicarse con /v1 y con la API de administración.

---

Formato de la cabecera

Authorization: Bearer oma_live_<secret>
Authorization: Bearer sk-<secret>
Cookie: auth_token=<dashboard-jwt>

No incluya credenciales de administración en la ruta de la URL ni en la cadena de consulta. La autenticación de administración solo se admite mediante cabecera/cookie.

---

Ejemplos para copiar y pegar

Solo lectura (listar proveedores). Use un token de acceso read:

curl -sS "$OMNIROUTE_URL/api/providers" \
  -H "Authorization: Bearer oma_live_<read-token>"

Modificación (crear una conexión con un proveedor). Use un token de acceso write/admin o una clave de API con el ámbito manage:

curl -sS -X POST "$OMNIROUTE_URL/api/providers" \
  -H "Authorization: Bearer oma_live_<write-or-admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","apiKey":"<upstream-key>"}'

Inferencia (no administración). Clave de API normal; no se requiere manage:

curl -sS "$OMNIROUTE_URL/v1/models" \
  -H "Authorization: Bearer sk-<inference-key>"

---

Errores actuales en tiempo de ejecución (no mostrar secretos)

Situación	Estado típico	Mensaje (anonimizado)
Sin credencial	401	Se requiere autenticación
oma_live_… no válido/caducado	401	Token de acceso no válido o caducado
Clave de API válida sin manage/admin	403	La clave de API carece del ámbito 'manage'. Habilítelo en el panel de Claves de API.
Clave de API ordinaria no válida en una ruta de administración	403	Token de administración no válido
Ámbito del Token de Acceso demasiado bajo	403	El ámbito del token de acceso '<have>' es insuficiente; se requiere '<need>'.

“Token de administración no válido” significa que el portador no fue aceptado como credencial de administración. Esto no indica qué familia debe generar. Use la tabla anterior: las claves de inferencia necesitan el ámbito manage; la CLI remota necesita oma_live_…; el panel usa la cookie de sesión.

---

Opción recomendada de privilegios mínimos

Cliente que realiza la llamada	Usar
Navegador	Sesión del panel
CLI en el host del servidor	Token de máquina
CLI en un portátil conectado a un servidor remoto	oma_live_… de omniroute connect
CI / scripts (solo gestión)	oma_live_… con el alcance mínimo necesario
CI que debe llamar tanto a /v1 como a /api	Clave de API con manage o dos credenciales

---

Código fuente de OmniRoute (a58000c7685f)