Management Authentication (Русский)

Матрицы областей

Области управления API-ключей и области токенов доступа — это разные словари. Области инструментов MCP — это третий словарь, проверяемый с помощью scopeMatches, а не любой из функций в таблицах ниже. Рядом: Три пространства имен областей.

Области токенов доступа (oma_live_…)

Область	Типичные операции
read	GET-запросы списка/статуса, которые разрешено видеть токену
write	Изменения (создание/обновление/удаление) ниже администратора
admin	Полный удаленный CLI / токен подключения (здесь по умолчанию пароль)

Токен с read не может вызывать маршрут write. Форма сообщения во время выполнения: Access token scope '<have>' is insufficient; '<need>' required.

Области управления API-ключей

Область	Значение
(нет)	Только Inference. Маршруты управления возвращают 403.
manage	API управления (тот же шлюз, что и ветвь API-ключа requireManagementAuth)
admin	Также удовлетворяет hasManageScope (рассматривается как способный к управлению)

Включите manage для ключа в пользовательском интерфейсе API Keys / API Manager. Не используйте повторно ключ клиента чата для автоматизации, если вы намеренно не предоставили эту область.

---

Как создать и отозвать

Сессия JWT панели управления

1. Откройте /login, войдите, используя пароль администратора (INITIAL_PASSWORD при первом запуске).
2. Куки auth_token является HttpOnly. Панель управления в браузере использует его автоматически.
3. Выйдите через /api/auth/logout. Долгосрочного секрета для копирования нет.

Токен machine-id для CLI

1. Запустите omniroute на том же хосте, что и сервер (loopback).
2. CLI создает токен machine-id в ~/.omniroute/ (chmod 600).
3. Это не работает с другой машины. Используйте Access Token для удаленного CLI.

Scoped Access Token (oma_live_…)

1. Панель управления: Settings → Access Tokens → создать (имя + область). Секрет показывается один раз.
2. Или CLI: omniroute connect <host> (пароль → токен). См. Remote Mode.
3. Заголовок: Authorization: Bearer oma_live_…
4. Отзовите с той же страницы Access Tokens (или удалите контекст CLI).
5. Сервер хранит только хеш. Относитесь к открытому тексту как к паролю.

API-ключ с областью действия manage

1. Панель управления: API Manager / API Keys → создать или отредактировать ключ → включить manage (или admin).
2. Заголовок: Authorization: Bearer sk-… (фактический префикс ключа).
3. Отзовите или удалите manage в том же пользовательском интерфейсе.
4. Принцип наименьших привилегий для автоматизации, не являющейся CLI: отдавайте предпочтение read Access Token для задач только с GET-запросами; используйте manage для API-ключа только тогда, когда вызывающая сторона также должна взаимодействовать с /v1 и управлением.

---

Формат заголовка

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

Не помещайте учетные данные управления в путь URL или строку запроса. Аутентификация управления осуществляется только через заголовок/куки.

---

Примеры для копирования

Только для чтения (список провайдеров). Используйте read Access Token:

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

Изменение (создание подключения провайдера). Используйте write/admin Access Token или API-ключ с областью действия 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>"}'

Вывод (не управление). Обычный API-ключ, manage не требуется:

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

---

Текущие ошибки выполнения (не выводить секреты)

Ситуация	Типичный статус	Сообщение (санировано)
Нет учетных данных	401	Authentication required
Недействительный/истекший oma_live_…	401	Invalid or expired access token
Действительный API-ключ без manage/admin	403	API key lacks 'manage' scope. Enable it in the API Keys dashboard.
Недействительный обычный API-ключ на маршруте управления	403	Invalid management token
Слишком низкая область действия Access Token	403	Access token scope '<have>' is insufficient; '<need>' required.

“Invalid management token” означает, что носитель не был принят в качестве учетных данных для управления. Это не говорит вам, какое семейство токенов следует использовать. Используйте таблицу выше: ключи для вывода требуют область manage; удаленный CLI требует oma_live_…; панель управления использует сессионные куки.

Рекомендуемый выбор с минимальными привилегиями

Вызывающий объект	Использование
Браузер	Сессия панели управления
CLI на хосте сервера	Токен машины
CLI на ноутбуке, взаимодействующий с удаленным сервером	oma_live_… из omniroute connect
CI / скрипты (только управление)	oma_live_… с наименьшей рабочей областью
CI, который должен вызывать как /v1, так и /api	Ключ API с manage или две учетные записи

---

Исходный код OmniRoute (a58000c7685f)