Начало
Авторизация и ключи
Агенту нужен один из двух bearer-токенов в заголовке Authorization::
- персональный API-ключ
aos3.– студент создаёт его в кабинете, срок 90 дней;sk_ … - OAuth access token – его получают MCP-клиенты (Claude.ai, ChatGPT, Codex) после входа и согласия студента, срок 1 час, обновляется refresh-токеном.
Оба вида проверяются одинаково: права определяют scopes, лимиты общие для REST и MCP.
Scopes#
| Scope | Что открывает | По умолчанию |
|---|---|---|
course: | уроки, эфиры, транскрипты, поиск, прогресс, профиль | да |
profile: | анкета и персональный план | да |
progress: | отметки уроков и шагов плана | нет, включается явно |
tutor: | чтение собственной истории тьютора | нет, включается явно |
mentoring: | личный менторинг (тарифы «С куратором / Лично с Даши») | нет, включается явно |
course: не открывает анкету и план – для них нужен profile:. tutor: и mentoring: никогда не выдаются по умолчанию и не добавляются к уже выпущенным ключам и подключениям. Не хватает права – ответ 403 INSUFFICIENT_ (в MCP – isError: с тем же кодом).
Жизненный цикл ключа#
- Создание – в кабинете, после входа не старше 10 минут:
POST. Секрет показывается один раз./ api/ v1/ keys - Ротация –
POST: старый ключ отзывается, новый получает то же имя и scopes на 90 дней./ api/ v1/ keys/ { id} / rotate - Отзыв –
DELETE./ api/ v1/ keys/ { id} - Журнал –
GET: последние вызовы REST и MCP по каждому ключу./ api/ v1/ keys/ calls
Управлять ключами можно только из кабинета: API-ключ и OAuth не могут выпускать ключи.
Способы авторизации#
Каждый маршрут содержит назначение, auth, scope, входные поля, ответ, ошибки, лимиты и curl. Имена типов ссылаются на полные JSON Schema: там все вложенные поля, варианты union, required, enum и pattern. ? в краткой форме – поле необязательно, | – значение может быть null; это разные случаи. Даты – ISO-8601, позиции видео – секунды. Query URL-encoded; числа query проверяются с coercion. Входные strict-object DTO запрещают неизвестные поля.
| Auth | Как передать | Границы |
|---|---|---|
| Кабинет | Cookie _, Secure / HttpOnly / SameSite=Lax / Path=/ | Сессия: 7 дней бездействия / 30 дней absolute; sensitive endpoints требуют auth_ ≤10 минут |
| Mini App | Authorization: | Sliding 15 минут, absolute 12 часов; не может управлять API-ключами |
| API-ключ | Authorization: | Личный ключ на 90 дней, scopes из кабинета |
| OAuth | Тот же bearer header | Access token 1 час; только там, где разрешён agentKey; flow и rotation |
Поля mentoring / offer (Me, AgentWhoami, ViewAsStudent) и mentoringWith / offer (CuratorEnrollment) приходят, только если запрос объявил X- (список через запятую, неизвестные значения игнорируются); без заголовка ответ – прежней формы, которую строгий клиент старого контракта (additionalProperties:) принимает. Заголовок меняет только форму ответа, не доступ. Кабинет шлёт его всегда; REST и MCP одинаково.
Когда предъявлены и bearer, и cookie, bearer имеет приоритет. Scope проверяется у API-ключей и OAuth-токенов; для сессии/TMA разрешённый метод определяется credential policy, а не строкой scope. course: не даёт доступ к анкете/плану без profile:. progress: разрешает aos_ и aos_; для собственной истории тьютора через MCP требуется отдельное opt-in разрешение tutor:; оно не входит в defaults.
Для маршрутов с ошибкой ORIGIN_ обязателен точный Origin:, либо при отсутствии Origin – Sec-. Это правило действует и для REST write-вызова API-ключом, если так объявлен маршрут. Query/path не используются для передачи bearer. JSON parser считает пустое тело {, затем применяет DTO; auth/login bodies ограничены 16 KiB.
Все ответы API получают Referrer-, nosniff, CSP, no-; персональные – private,, Vary:. Исключение: успешный аватар кэшируется приватно до суток. Файлы скачиваются как attachment с sandbox CSP. JSON-RPC и OAuth имеют отдельные форматы ошибок.