REST API
POST/ api/ v1/ auth/ tma
Проверить подписанную строку Telegram.WebApp.initData и выдать TMA bearer и профиль.
| Поле | Значение |
|---|---|
| URL | POST |
| Доступ | Без авторизации |
| Scope для ключей | не требуется |
| operationId | authTma |
Описание#
Проверить подписанную строку Telegram. и выдать TMA bearer и профиль. Нельзя подменять её неподписанным JSON пользователя.
Auth: без авторизации. Scope: не требуется.
Path: параметров нет.
Query: нет объявленных полей.
Body: application/, TmaExchangeRequest. Все вложенные поля и варианты – по ссылке.
| Поле | Тип | Обязательно | Ограничения |
|---|---|---|---|
initData | string | да | длина ≥ 1; длина ≤ 8192 |
Ответ · статус и структура
Ответ: 200 application/, TmaExchangeResponse.
Краткая форма: {.
Пример 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 , 403 , 403 , 503 , 429 , 401 ; общие ошибки.
Лимиты: Защита от перебора: при превышении – 429 , повторить после Retry-.
Запрос · 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
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.
| Статус | Тип | Схема | Описание |
|---|---|---|---|
| 200 | application/json | TmaExchangeResponse | Успех |
| ошибка | application/json | ErrorBody | Ошибка; коды: VALIDATION_FAILED, ORIGIN_REJECTED, NO_ENTITLEMENT, ENTITLEMENT_UNAVAILABLE, RATE_LIMITED, LOGIN_INVALID |
Машиночитаемый контракт: openapi.json, операция authTma.