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

Агенту нужен один из двух 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`](/docs/api/keys/keys-create). Секрет показывается один раз.
2. Ротация – [`POST /api/v1/keys/{id}/rotate`](/docs/api/keys/keys-rotate): старый ключ отзывается, новый получает то же имя и scopes на 90 дней.
3. Отзыв – [`DELETE /api/v1/keys/{id}`](/docs/api/keys/keys-revoke).
4. Журнал – [`GET /api/v1/keys/calls`](/docs/api/keys/keys-calls): последние вызовы REST и MCP по каждому ключу.

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

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

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

> [!NOTE]
> `aos_live_...` – условная маска, **не действующий формат токена**. Заменяйте её реальным секретом: API-ключ / OAuth access token имеют `aos3.sk_` + 43 base64url-символа, TMA – `aos3.tt_` + 43. Cookie `__Host-aos_sess` содержит 43 base64url-символа. Примеры данных синтетические: `student@example.com`, демонстрационный Telegram id, UUID и учебный текст.

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

Поля `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 имеют отдельные форматы ошибок.
