Состояние API

API состояния и сессий позволяет проверить доступность сервиса, открыть и продлить сессию консоли, выйти и получить билет для запроса к сайту.

Метод	Путь	Действие
`GET`	`/health`	Проверить состояние API
`POST`	`/auth/session`	Открыть сессию
`POST`	`/auth/telegram`	Войти через Telegram
`POST`	`/auth/refresh`	Продлить сессию
`POST`	`/auth/logout`	Закрыть текущую сессию
`POST`	`/auth/logout-all`	Закрыть все свои сессии
`GET`	`/auth/me`	Получить текущую сессию
`POST`	`/auth/ticket`	Получить билет для запроса к сайту

Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Полный перечень эндпоинтов — в справочнике API.

Проверить состояние API

GET /health

Отвечает, жив ли сервис и доступна ли база; токен не нужен, префикса сайта нет. Например:

curl -s "$API/health"

Параметры пути. У операции нет собственных параметров пути.

Параметры строки запроса. Дополнительных параметров нет.

Тело запроса. Не требуется.

Ответ

{ "ok": true, "db": true, "realm": "prod" }

Поле	Тип	Описание
`ok`	boolean	сервис отвечает
`db`	boolean	база доступна
`realm`	строка	окружение экземпляра API: `prod` у `https://onpress.pro/api/v2`

Ошибки

Код	HTTP	Когда	Что делать
—	503	сервис жив, база недоступна: `"db": false`	повторить позже

Эндпоинты /auth

Эндпоинты /auth обслуживают сессию консоли и работают без префикса сайта. Все они, кроме GET /auth/me, принимают только POST; на GET они отвечают 405 method_not_allowed с заголовком Allow: POST. Все, кроме входа, работают по кукам сессии, а на запрос с чужого адреса API отвечает 403 cross_origin. Отказы приходят в форме {code, message, data: {status}}, попыток входа — до 30 в минуту с одного адреса. Например, проверка сессии без куки:

curl -s "$API/auth/me"

{ "code": "no_session", "message": "sign in first", "data": { "status": 401 } }

Открыть сессию

POST /auth/session

Обменивает ID-токен Firebase на сессию консоли. API принимает вход почтой с паролем и через Google; почта должна быть подтверждена, а человек — уже быть пользователем OnPress или приглашенным на сайт. Ответ — 201 и две httpOnly-куки: сессионная на 15 минут и долгая для продления на 30 дней. Например:

curl -s -X POST "$API/auth/session" \
  -H "Authorization: Bearer $FIREBASE_ID_TOKEN"

Параметры пути. У операции нет собственных параметров пути.

Заголовки. Передайте ID-токен в Authorization: Bearer либо id_token в теле JSON.

Параметры строки запроса. Дополнительных параметров нет.

Параметры тела

Параметр	Тип	Обязателен	По умолчанию	Описание
`id_token`	string	если нет Authorization	—	ID-токен Firebase после входа; заголовок Authorization: Bearer имеет приоритет

Ответ

{
  "success": true,
  "user": { "id": 42, "email": "anna@example.com", "name": "Anna", "avatar": "https://lh3.googleusercontent.com/…", "is_super_admin": false },
  "session": { "id": "…", "expires_at": "…", "expires_in": 900, "realm": "prod" },
  "impersonated_by": null
}

avatar — фото Google, иначе Telegram, иначе Gravatar; вход через Google обновляет фото при каждом входе.

Ошибки

Код	HTTP	Когда	Что делать
`missing_id_token`	401	нет ID-токена	передать токен в `Authorization: Bearer`
`invalid_id_token`	401	ID-токен не прошел проверку или истек	войти в Firebase заново
`email_required`	403	у аккаунта Firebase нет почты	войти почтой или через Google
`email_not_verified`	403	почта не подтверждена	открыть письмо Firebase и подтвердить
`provider_not_allowed`	403	вход не почтой и не через Google	войти почтой с паролем или через Google
`user_not_found`	403	почты нет среди пользователей OnPress	попросить администратора сайта добавить почту
`cross_origin`	403	запрос не с адреса консоли	войти из консоли
`too_many_requests`	429	больше 30 попыток входа в минуту	подождать `Retry-After` секунд
`auth_not_configured`	503	вход не настроен на сервере	повторить позже

Войти через Telegram

POST /auth/telegram

Открывает сессию по данным виджета входа Telegram; аккаунт Telegram должен быть уже привязан к пользователю OnPress. Ответ и куки — как у POST /auth/session. Например:

curl -s -X POST "$API/auth/telegram" \
  -H "Content-Type: application/json" \
  -d '{"id": 123456789, "first_name": "Anna", "auth_date": 1793135000, "hash": "…"}'

Параметры пути. У операции нет собственных параметров пути.

Параметры строки запроса. Дополнительных параметров нет.

Параметры тела

Поле	Тип	Обязателен	По умолчанию	Описание
`id`	число	да	—	id пользователя Telegram
`auth_date`	число	да	—	время входа, unix; не старше суток
`hash`	строка	да	—	подпись виджета
`first_name`, `last_name`, `username`, `photo_url`	строка	нет	—	остальные поля виджета, как он их прислал

Ответ

{
  "success": true,
  "user": {
    "id": 42,
    "email": "anna@example.com",
    "name": "Anna",
    "avatar": null,
    "is_super_admin": false
  },
  "session": {
    "id": "SESSION_ID",
    "expires_at": "2026-10-30T16:15:00.000Z",
    "expires_in": 900,
    "realm": "prod"
  },
  "impersonated_by": null
}

Ошибки

Код	HTTP	Когда	Что делать
`invalid_telegram_data`	400	нет `id`, `auth_date` или `hash`	передать данные виджета целиком
`invalid_telegram_hash`	401	подпись не сходится	войти через виджет заново
`telegram_auth_expired`	401	вход старше суток	войти через виджет заново
`user_not_found`	403	Telegram не привязан к пользователю OnPress	войти почтой или через Google
`cross_origin`	403	запрос не с адреса консоли	войти из консоли
`too_many_requests`	429	больше 30 попыток входа в минуту	подождать `Retry-After` секунд

Продлить сессию

POST /auth/refresh

Продлевает сессию по долгой куке и меняет ее секрет. Ответ — как у POST /auth/session, со статусом 200. Например:

curl -s -X POST "$API/auth/refresh" -b cookies.txt -c cookies.txt

Параметры пути. У операции нет собственных параметров пути.

Параметры строки запроса. Дополнительных параметров нет.

Тело запроса. Не требуется.

Ответ

{
  "success": true,
  "user": {
    "id": 42,
    "email": "anna@example.com",
    "name": "Anna",
    "avatar": null,
    "is_super_admin": false
  },
  "session": {
    "id": "SESSION_ID",
    "expires_at": "2026-10-30T16:15:00.000Z",
    "expires_in": 900,
    "realm": "prod"
  },
  "impersonated_by": null
}

Ошибки

Код	HTTP	Когда	Что делать
`no_session`	401	нет долгой куки	войти заново
`session_expired`	401	сессия истекла или отозвана	войти заново
`user_not_found`	403	пользователя больше нет	проверьте параметр из message и повторите запрос

Закрыть текущую сессию

POST /auth/logout

Закрывает сессию на этом устройстве и стирает куки. Если сессии уже нет, запрос завершается успешно с revoked: 0. Например:

curl -s -X POST "$API/auth/logout" -b cookies.txt

Параметры пути. У операции нет собственных параметров пути.

Параметры строки запроса. Дополнительных параметров нет.

Тело запроса. Не требуется.

Ответ

{ "success": true, "revoked": 1 }

Ошибки

Код	HTTP	Когда	Что делать
`cross_origin`	403	Origin не совпадает с адресом консоли	отправьте запрос из консоли

Закрыть все свои сессии

POST /auth/logout-all

Закрывает все сессии пользователя на всех устройствах; токен API продолжает работать. Например:

curl -s -X POST "$API/auth/logout-all" -b cookies.txt

Параметры пути. У операции нет собственных параметров пути.

Параметры строки запроса. Дополнительных параметров нет.

Тело запроса. Не требуется.

Ответ

{ "success": true, "revoked": 3 }

Ошибки

Код	HTTP	Когда	Что делать
`no_session`	401	нет действующей сессии	войти

Получить текущую сессию

GET /auth/me

Возвращает, кто вошел, и id сессии; профиль целиком — GET /me из справочника пользователей. Например:

curl -s "$API/auth/me" -b cookies.txt

Параметры пути. У операции нет собственных параметров пути.

Параметры строки запроса. Дополнительных параметров нет.

Тело запроса. Не требуется.

Ответ

{
  "success": true,
  "user": { "id": 42, "email": "anna@example.com", "name": "Anna", "avatar": "https://lh3.googleusercontent.com/…", "is_super_admin": false },
  "session": { "id": "…", "realm": "prod" },
  "impersonated_by": null
}

Ошибки

Код	HTTP	Когда	Что делать
`no_session`	401	нет действующей сессии	войти
`user_not_found`	403	пользователя больше нет	проверьте параметр из message и повторите запрос

Получить билет для запроса к сайту

POST /auth/ticket

Выдает одноразовый билет на две минуты для запроса консоли к API на домене сайта: браузер не отправляет куку консоли на чужой домен. API выдает билет только по сессии консоли; с токеном op_ билет не нужен — API на домене сайта принимает токен напрямую. Назовите сайт полем site_id или domain в теле или строке запроса, а билет передайте сайту заголовком Authorization: Bearer или X-OnPress-Ticket. Например:

curl -s -X POST "$API/auth/ticket" -b cookies.txt \
  -H "Content-Type: application/json" \
  -d '{"site_id": "x9HTLHECq"}'

Параметры пути. У операции нет собственных параметров пути.

Параметры строки запроса

Параметр	Тип	Обязателен	По умолчанию	Описание
`site_id`	string	site_id или domain	—	id сайта, если его нет в теле
`domain`	string	если нет site_id	—	домен сайта, если его нет в теле

Параметры тела

Поле	Тип	Обязателен	По умолчанию	Описание
`site_id`	строка	site_id или domain	—	id сайта
`domain`	строка	если нет site_id	—	домен сайта, если `site_id` не задан

Ответ

{ "success": true, "ticket": "…", "issued_at": 1793135000, "expires_at": 1793135120, "blog_id": 233, "jti": "…", "ttl": 120 }

Поле	Описание
`ticket`	билет
`issued_at`, `expires_at`	время выдачи и конца действия, unix
`blog_id`	внутренний id сайта
`jti`	id билета
`ttl`	срок действия в секундах

Ошибки

Код	HTTP	Когда	Что делать
`no_session`	401	нет сессии консоли — например, запрос с токеном `op_`	с токеном обращаться к API сайта напрямую
`blog_required`	400	сайт не назван	передать `site_id`
`site_not_found`	404	сайта с таким `site_id` или доменом нет	проверить `site_id` или домен
`insufficient_role`	403	вы не администратор этого сайта	войти под администратором сайта
`cross_origin`	403	запрос не с адреса консоли	запросить билет из консоли