# POST /api/v1/auth/tma

Проверить подписанную строку Telegram.WebApp.initData и выдать TMA bearer и профиль.

| Поле | Значение |
| --- | --- |
| URL | `POST https://aos.edgelab.space/api/v1/auth/tma` |
| Доступ | Без авторизации |
| Scope для ключей | не требуется |
| operationId | `authTma` |

## Описание

Проверить подписанную строку `Telegram.WebApp.initData` и выдать TMA bearer и профиль. Нельзя подменять её неподписанным JSON пользователя.

**Auth:** без авторизации. **Scope:** не требуется.

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

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

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

| Поле       | Тип      | Обязательно | Ограничения             |
| ---------- | -------- | ----------- | ----------------------- |
| `initData` | `string` | да          | длина ≥ 1; длина ≤ 8192 |

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

**Ответ:** 200 `application/json`, [TmaExchangeResponse](/docs/schemas#tmaexchangeresponse).

Краткая форма: `{ session: TmaToken, me: Me }`.

Пример JSON; значения демонстрационные.

```json
{
  "session": {
    "token": "aos3.tt_Zml4dHVyZS1vbmx5LW5vdC1hLXJlYWwtdG1hLXRva2V",
    "expiresAt": "2026-11-04T09:15:00Z",
    "absoluteExpiresAt": "2026-11-04T21:00:00Z"
  },
  "me": {
    "student": {
      "id": "0b9a6f2e-4c1d-4f7e-9a51-3c2d8e7f6a10",
      "tgId": 100000001,
      "name": "Александр Петров",
      "username": "alex_petrov",
      "avatarUrl": null
    },
    "flow": "agentos3",
    "tier": "personal",
    "access": {
      "state": "active",
      "checkedAt": "2026-11-04T09:00:00Z"
    },
    "onboarding": {
      "status": "draft",
      "done": false
    },
    "planReady": false,
    "authKind": "tma",
    "features": {
      "tutor": false,
      "agentKeys": false,
      "dictation": true
    },
    "limits": {
      "tutorMessagesPerDay": 100,
      "tutorUsdPerDay": 2.5
    }
  }
}
```

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

**Лимиты:** Защита от перебора: при превышении – `429 RATE_LIMITED`, повторить после `Retry-After`.

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

```json
{
  "initData": "query_id=AAF&user=%7B%22id%22%3A100000001%2C%22first_name%22%3A%22Alex%22%7D&auth_date=1793782800&signature=fixture&hash=0000"
}
```

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

```bash
curl -sS -i -X POST https://aos.edgelab.space/api/v1/auth/tma \
  -H 'Origin: https://aos.edgelab.space' \
  -H 'Content-Type: application/json' \
  -d '{"initData":"query_id=AAF&user=%7B%22id%22%3A100000001%2C%22first_name%22%3A%22Alex%22%7D&auth_date=1793782800&signature=fixture&hash=0000"}'
```

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

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

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

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