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

Четыре способа аутентификации в API TGIO.APP.

Способ 1: JWT Token

Получите токен, отправив Telegram initData:

curl -X POST https://back.tgio.app/api/auth/telegram \
  -H "Content-Type: application/json" \
  -d '{"initData": "<raw initData string>"}'

Ответ:

{
  "accessToken": "eyJ...",
  "user": { "id": 1, "telegramId": 123456, "username": "myname" }
}

Используйте токен в заголовке каждого запроса:

Authorization: Bearer <accessToken>

Время жизни токена: 7 дней.

Способ 2: Telegram Login Widget

Для веб-приложений с Telegram Login Widget:

curl -X POST https://back.tgio.app/api/auth/login-widget \
  -H "Content-Type: application/json" \
  -d '{"id": 123, "first_name": "Name", "hash": "...", "auth_date": 123}'

Ответ: аналогичен способу 1.

Способ 3: Telegram initData Header

Для Mini App — передавайте initData с каждым запросом:

x-telegram-init-data: <raw initData string>

Токен не нужен — бот проверяет initData напрямую.

Регистрация по email без пароля

В web dashboard регистрация выполняется без пароля: пользователь подтверждает email одноразовым кодом.

Используются эндпоинты:

• POST /api/auth/email/send-otp
• POST /api/auth/email/verify-otp

Если аккаунта с этим email ещё нет, он создаётся автоматически при успешной верификации кода.

Способ 4: API-токен (рекомендуется для интеграций)

Самый удобный способ для скриптов, CI/CD и внешних интеграций.

1. Создайте токен

Откройте бота → Настройки → API Токены → Создать новый токен.

Укажите название и нужные права (scopes). Скопируйте токен — он показывается только один раз.

Токен выглядит так: tgio_sk_a3933ec...

2. Используйте токен в запросах

Передавайте токен в заголовке Authorization:

curl https://back.tgio.app/api/links \
  -H "Authorization: Bearer tgio_sk_a3933ec..."

Примеры

Получить список ссылок:

curl https://back.tgio.app/api/links \
  -H "Authorization: Bearer tgio_sk_ВАШ_ТОКЕН"

Создать короткую ссылку:

curl -X POST https://back.tgio.app/api/links \
  -H "Authorization: Bearer tgio_sk_ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "title": "My Link"}'

Получить статистику канала:

curl https://back.tgio.app/api/channels \
  -H "Authorization: Bearer tgio_sk_ВАШ_ТОКЕН"

Scopes (права доступа)

Scope	Описание
*	Полный доступ (по умолчанию)
read:links	Чтение ссылок и статистики кликов
write:links	Создание и редактирование ссылок
read:stats	Чтение аналитики
read:channels	Чтение данных каналов
read:pixels	Чтение пикселей
write:pixels	Создание и редактирование пикселей

TIP

Для максимальной безопасности выдавайте токену только те права, которые реально нужны.

Ошибки токена

Код	Причина
401	Токен не передан или невалидный
401	Токен отозван (revoked)
401	Токен просрочен (expired)
403	У токена нет нужного scope для этого эндпоинта

Управление токенами

API для программного создания и отзыва токенов: Токены.

Привязка Email и Telegram

Эндпоинты привязки:

• POST /api/auth/email/send-link-otp
• POST /api/auth/email/verify-link-otp
• POST /api/auth/telegram/link-widget

Правила объединения аккаунтов:

• Привязка email к Telegram-аккаунту в Mini App выполняется только один раз.
• Если email уже связан с аккаунтом, при подтверждении кода аккаунты объединяются.
• При объединении тарифов сохраняется более дорогой активный тариф (starter < pro < business).
• Если один аккаунт платный, после объединения платный тариф применяется для связанного аккаунта.
• При объединении автоматически переносится ownership пользовательских ресурсов со старого аккаунта на целевой: ссылки, пиксели, каналы, мониторинги, secure sharing и связанные сущности.
• Повторная привязка другого Telegram-аккаунта к уже связанному email отклоняется.

Привязка Telegram в web dashboard

Используйте данные Telegram Login Widget и отправляйте их на защищённый endpoint:

curl -X POST https://back.tgio.app/api/auth/telegram/link-widget \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"id":"123456","first_name":"John","username":"john_doe","auth_date":"...","hash":"..."}'

Endpoint проверяет hash Telegram Login Widget, привязывает Telegram к текущему аккаунту и при необходимости объединяет тарифы по правилу «сохраняется более дорогой активный тариф» с переносом пользовательских ресурсов на итоговый аккаунт.

Passkey (WebAuthn)

В web dashboard доступен вход по passkey и управление passkey в разделе Security.

Эндпоинты регистрации (требуют JWT):

• POST /api/auth/passkey/register/options
• POST /api/auth/passkey/register/verify
• GET /api/auth/passkey/list
• DELETE /api/auth/passkey/:id

Эндпоинты входа (публичные):

• POST /api/auth/passkey/login/options
• POST /api/auth/passkey/login/verify

Типовой сценарий входа:

1. Клиент отправляет email на POST /api/auth/passkey/login/options.
2. Сервер отдаёт challenge и параметры WebAuthn для браузера.
3. Клиент вызывает WebAuthn (startAuthentication) и отправляет ответ на POST /api/auth/passkey/login/verify.
4. При успешной проверке сервер возвращает access_token, refresh_token, user, subscription (как при email OTP).