К содержанию
AgentOSДокументация
  • Загружаем индекс…
llms.txtКабинет

Начало

Авторизация и ключи

Агенту нужен один из двух bearer-токенов в заголовке Authorization: Bearer …:

  • персональный API-ключ aos3.sk_… – студент создаёт его в кабинете, срок 90 дней;
  • OAuth access token – его получают MCP-клиенты (Claude.ai, ChatGPT, Codex) после входа и согласия студента, срок 1 час, обновляется refresh-токеном.

Оба вида проверяются одинаково: права определяют scopes, лимиты общие для REST и MCP.

Scopes#

ScopeЧто открываетПо умолчанию
course:readуроки, эфиры, транскрипты, поиск, прогресс, профильда
profile:readанкета и персональный планда
progress:writeотметки уроков и шагов плананет, включается явно
tutor:readчтение собственной истории тьюторанет, включается явно
mentoring:readличный менторинг (тарифы «С куратором / Лично с Даши»)нет, включается явно

course:read не открывает анкету и план – для них нужен profile:read. tutor:read и mentoring:read никогда не выдаются по умолчанию и не добавляются к уже выпущенным ключам и подключениям. Не хватает права – ответ 403 INSUFFICIENT_SCOPE (в MCP – isError: true с тем же кодом).

Жизненный цикл ключа#

  1. Создание – в кабинете, после входа не старше 10 минут: POST /api/v1/keys. Секрет показывается один раз.
  2. Ротация – POST /api/v1/keys/{id}/rotate: старый ключ отзывается, новый получает то же имя и scopes на 90 дней.
  3. Отзыв – DELETE /api/v1/keys/{id}.
  4. Журнал – GET /api/v1/keys/calls: последние вызовы REST и MCP по каждому ключу.

Управлять ключами можно только из кабинета: API-ключ и OAuth не могут выпускать ключи.

Способы авторизации#

Каждый маршрут содержит назначение, auth, scope, входные поля, ответ, ошибки, лимиты и curl. Имена типов ссылаются на полные JSON Schema: там все вложенные поля, варианты union, required, enum и pattern. ? в краткой форме – поле необязательно, | null – значение может быть null; это разные случаи. Даты – ISO-8601, позиции видео – секунды. Query URL-encoded; числа query проверяются с coercion. Входные strict-object DTO запрещают неизвестные поля.

AuthКак передатьГраницы
КабинетCookie __Host-aos_sess, Secure / HttpOnly / SameSite=Lax / Path=/Сессия: 7 дней бездействия / 30 дней absolute; sensitive endpoints требуют auth_at ≤10 минут
Mini AppAuthorization: Bearer <TMA_TOKEN>Sliding 15 минут, absolute 12 часов; не может управлять API-ключами
API-ключAuthorization: Bearer aos_live_...Личный ключ на 90 дней, scopes из кабинета
OAuthТот же bearer headerAccess token 1 час; только там, где разрешён agentKey; flow и rotation

Поля mentoring / offer (Me, AgentWhoami, ViewAsStudent) и mentoringWith / offer (CuratorEnrollment) приходят, только если запрос объявил X-Aos-Accept: enrollment-labels (список через запятую, неизвестные значения игнорируются); без заголовка ответ – прежней формы, которую строгий клиент старого контракта (additionalProperties: false) принимает. Заголовок меняет только форму ответа, не доступ. Кабинет шлёт его всегда; REST и MCP одинаково.

Когда предъявлены и bearer, и cookie, bearer имеет приоритет. Scope проверяется у API-ключей и OAuth-токенов; для сессии/TMA разрешённый метод определяется credential policy, а не строкой scope. course:read не даёт доступ к анкете/плану без profile:read. progress:write разрешает aos_mark_lesson и aos_update_plan_milestone; для собственной истории тьютора через MCP требуется отдельное opt-in разрешение tutor:read; оно не входит в defaults.

Для маршрутов с ошибкой ORIGIN_REJECTED обязателен точный Origin: https://aos.edgelab.space, либо при отсутствии Origin – Sec-Fetch-Site: same-origin. Это правило действует и для REST write-вызова API-ключом, если так объявлен маршрут. Query/path не используются для передачи bearer. JSON parser считает пустое тело {}, затем применяет DTO; auth/login bodies ограничены 16 KiB.

Все ответы API получают Referrer-Policy: no-referrer, nosniff, CSP, no-store; персональные – private, no-store, Vary: Cookie, Authorization. Исключение: успешный аватар кэшируется приватно до суток. Файлы скачиваются как attachment с sandbox CSP. JSON-RPC и OAuth имеют отдельные форматы ошибок.