# Аутентификация

Один способ: токен в заголовке. Ни ключей в теле запроса, ни выдачи ключа
по анкете, ни двух разных схем для двух разных API.

## Токен в заголовке

```bash
curl -X GET 'https://school.example.com/api/v1/courses' \
  -H 'Authorization: Bearer lms_live_a8f3c1e9d2b74a5f8e0c1d3b5a7f9e2c' \
  -H 'Accept: application/json'
```

Почему в заголовке, а не параметром: параметры попадают в журналы прокси,
в историю браузера и в отчёты об ошибках. Заголовок — нет.

**Только HTTPS.** Обычный HTTP отвечает `400` без перенаправления: перенаправление
с POST теряет тело и порождает баги, которые ищут днями.

## Боевой и тестовый

Префикс токена информативен:

| Префикс | Что это |
|---|---|
| `lms_live_` | Боевой ключ |
| `lms_test_` | Ключ [песочницы](/api/sandbox/) |

Это не украшение. Случайно закоммиченный ключ с таким префиксом опознаётся
сканером секретов — и отзывается до того, как им кто-нибудь воспользуется.
Ключ вида `a8f3c1e9…` не опознаётся ничем.

## Где взять ключ

Школа заводит ключи сама, в настройках. Не по заявке нам: коробка стоит на вашем
сервере, мы к ней не касаемся, и требовать обращения ради ключа было бы странно.
Подробности — [Ключи](/api/keys/).

**Значение показывается один раз**, при создании: в базе лежит только хеш.

## Действие от лица пользователя

Отдельный сценарий: интеграция выполняет действие **от лица конкретного человека** —
например, бот отправляет ответ на задание от имени ученика.

```
X-On-Behalf-Of: usr_01HQZX3M8K4N2P
```

Работает только с ключом, имеющим право на запись по пользователям, и записывается
в журнал аудита как «действие выполнено интеграцией X от имени пользователя Y».

**Никакой подмены личности в тени.** Это важно не для нас, а для разбора: через
месяц вопрос «кто отправил этот ответ» должен иметь ответ, а не догадку.

## Одноразовая ссылка входа

Нужна письмам, ботам и внешним лендингам: человек нажимает кнопку и попадает
в школу авторизованным, без ввода пароля.

**Одноразовая.** Сработает у того, кто откроет её первым; второй переход получит
отказ словами. Обычная ссылка входа живёт **15 минут**, ссылка из письма о доступе
в школу — **7 дней**: такое письмо читают вечером и в выходные.

**Ведёт туда, где человеку положено быть.** После перехода школа сама решает куда:
сотрудника — в админку, ученика — в кабинет. Та же функция, что у обычного входа.

**Подтверждает почту** — ту, на которую ушла ссылка. Если адрес в анкете за это
время сменился, подтверждения нет: письмо читал не хозяин нового адреса.

**Не заменяет код защиты.** У владельца, администратора и менеджера после перехода
форма просит код из приложения, а если он ещё не настроен — настроить. Ссылка,
пересланная в чат, без кода в школу не пустит.

## Чего в аутентификации нет

**OAuth и авторизации сторонних приложений.** Ключ заводит школа и отдаёт тому,
кому доверяет. Модель «пользователь разрешает приложению доступ к своим данным»
в первой версии не нужна: интеграции пишет сама школа или её подрядчик.

**Токена ученика.** Дать ученику ключ на чтение своих данных технически возможно
и модель прав это позволяет, но такой возможности сейчас нет.