Синапсия Документация

API Reference

Клиентское API для авторизации пользователей. Подключение провайдеров, OAuth, Email OTP, сессии.

Base URL: https://auth.synapsea.agency

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

Все запросы требуют заголовок X-Synapsea-Key с API-ключом проекта (sa_live_xxx или sa_test_xxx). Для проверки сессии — дополнительно Authorization: Bearer <session_token>.

Провайдеры

Получить список доступных провайдеров и методов для вашего проекта.

GET
/api/v1/auth/providers

Список включённых провайдеров (Google, VK, Telegram и т.д.) и их методов.

Auth: X-Synapsea-Key

Response (200)

{
  "providers": [
    { "id": "google", "name": "Google", "methods": ["oauth", "id_token"] },
    { "id": "vk", "name": "VK ID", "methods": ["oauth", "silent_token"] },
    { "id": "telegram", "name": "Telegram", "methods": ["oidc", "widget", "miniapp"] }
  ]
}

Попробовать

OAuth — вход через соцсети

Инициировать OAuth-redirect и обработать callback.

POST
/api/v1/auth/sign-in/social

Получить URL для перенаправления пользователя к провайдеру.

Auth: X-Synapsea-Key

Request Body

{
  "provider": "google",
  "method": "oauth",
  "callbackURL": "https://yoursite.com/auth/callback"
}

Response (200)

{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}
GET
/api/v1/auth/callback/:provider

Пользователь возвращается сюда после авторизации. Сервис создаёт сессию и редиректит на ваш callbackURL с session_token и user_id.

Auth: нет (редирект от провайдера)

Response (200)

HTTP 302 → callbackURL?session_token=sa_sess_...&user_id=uuid

Токены и SDK

Проверка токенов от клиентских SDK (Google One Tap, VK silent_token и т.д.).

POST
/api/v1/auth/verify-token

Проверить credential/idToken от Google One Tap, VK silent_token, Yandex instant_token.

Auth: X-Synapsea-Key

Request Body

{
  "provider": "google",
  "method": "id_token",
  "credential": "eyJhbGciOiJSUzI1NiIs..."
}

Response (200)

{
  "user": { "id": "uuid", "email": "...", "name": "...", "avatarUrl": "...", "provider": "google" },
  "session_token": "sa_sess_...",
  "isNewUser": false
}
POST
/api/v1/auth/sign-in/telegram/widget

Проверить данные Telegram Login Widget (HMAC-SHA256).

Auth: X-Synapsea-Key

Request Body

{
  "id": 123456789,
  "first_name": "Имя",
  "username": "user",
  "auth_date": 1710756000,
  "hash": "..."
}

Response (200)

{
  "user": { "id": "...", "name": "...", "username": "...", "provider": "telegram" },
  "session_token": "sa_sess_...",
  "isNewUser": true
}

Email OTP

Безпарольный вход по коду на email.

POST
/api/v1/auth/sign-in/email-otp/send

Отправить 6-значный код на email. Код действует 5 минут.

Auth: X-Synapsea-Key

Request Body

{ "email": "user@example.com" }

Response (200)

{ "success": true, "message": "OTP sent", "expiresIn": 300 }
POST
/api/v1/auth/sign-in/email-otp/verify

Подтвердить код и создать сессию.

Auth: X-Synapsea-Key

Request Body

{ "email": "user@example.com", "code": "123456" }

Response (200)

{
  "user": { "id": "...", "email": "user@example.com" },
  "session_token": "sa_sess_...",
  "isNewUser": false
}

Сессия

Проверка и завершение сессии.

GET
/api/v1/auth/session

Получить данные текущей сессии и пользователя. Используйте на каждом защищённом запросе.

Auth: X-Synapsea-Key + Authorization: Bearer <session_token>

Response (200)

{
  "user": {
    "id": "uuid",
    "email": "user@gmail.com",
    "emailVerified": true,
    "name": "John",
    "avatarUrl": "https://...",
    "provider": "google",
    "createdAt": "2026-03-18T10:00:00Z"
  },
  "session": {
    "id": "sess_...",
    "expiresAt": "2026-03-25T12:30:00Z"
  }
}
POST
/api/v1/auth/sign-out

Завершить сессию. Токен становится невалидным.

Auth: X-Synapsea-Key + Authorization: Bearer <session_token>

Response (200)

{ "success": true }

Callback URL для провайдеров

Укажите в настройках провайдера (Google, VK и т.д.):

https://auth.synapsea.agency/callback/<provider>

Например: https://auth.synapsea.agency/callback/google