# POST /api/v1/auth/password/setup

Запросить письмо установки/смены email.

| Поле | Значение |
| --- | --- |
| URL | `POST https://aos.edgelab.space/api/v1/auth/password/setup` |
| Доступ | Cookie кабинета · Mini App (TMA) |
| Scope для ключей | ключи не принимаются – только кабинет (403 `CREDENTIAL_NOT_ALLOWED`) |
| operationId | `authPasswordSetup` |

## Описание

Запросить письмо установки/смены email. Ровно одно из `email` и `orderEmail: true`; во втором случае полный адрес заказа разрешается сервером и не возвращается. Нужен Telegram-вход не старше 10 минут либо правильный `currentPassword`, если пароль уже есть. Вход по email-коду не считается свежим Telegram-входом. Успех всегда 204, даже если адрес занят; без mailer – 404.

**Auth:** сессия кабинета (cookie) / TMA bearer. **Scope:** не требуется.

**Path:** параметров нет.

**Query:** нет объявленных полей.

**Body:** `application/json`, [PasswordSetupRequest](/docs/schemas#passwordsetuprequest). Все вложенные поля и варианты – по ссылке.

| Поле              | Тип      | Обязательно | Ограничения                                           |
| ----------------- | -------- | ----------- | ----------------------------------------------------- |
| `email`           | `string` | нет         | длина ≤ 254; формат "email"; pattern см. полную схему |
| `orderEmail`      | `true`   | нет         | –                                                     |
| `currentPassword` | `string` | нет         | длина ≥ 1; длина ≤ 128                                |

**Ответ · статус и структура**

**Ответ:** 204, без тела.

**Ошибки:** `401 UNAUTHENTICATED`, `403 NO_ENTITLEMENT`, `503 ENTITLEMENT_UNAVAILABLE`, `429 RATE_LIMITED`, `403 ORIGIN_REJECTED`, `422 VALIDATION_FAILED`, `401 LOGIN_INVALID`, `401 REAUTH_REQUIRED`, `409 VERSION_CONFLICT`, `404 NOT_FOUND`, `403 CREDENTIAL_NOT_ALLOWED`; [общие ошибки](/docs/errors).

**Лимиты:** 3/10 min/student; защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`.

**Запрос · JSON**

```json
{
  "email": "student@example.com"
}
```

**Пример · curl**

```bash
curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/password/setup \
  --cookie '__Host-aos_sess=SESSION_PLACEHOLDER' \
  -H 'Origin: https://aos.edgelab.space' \
  -H 'Content-Type: application/json' \
  -d '{"email":"student@example.com"}'
```

## Ответы по контракту

Тело запроса: [PasswordSetupRequest](/docs/schemas#passwordsetuprequest).

| Статус | Тип | Схема | Описание |
| --- | --- | --- | --- |
| 204 | – | – | Успех |
| ошибка | application/json | [ErrorBody](/docs/schemas#errorbody) | Ошибка; коды: UNAUTHENTICATED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, ORIGIN_REJECTED, VALIDATION_FAILED, LOGIN_INVALID, REAUTH_REQUIRED, VERSION_CONFLICT, NOT_FOUND |

Машиночитаемый контракт: [openapi.json](/docs/openapi.json), операция `authPasswordSetup`.
