Бюро Цифровых Технологий

База знаний

Документация «Вираж»

База знаний по продуктам и API экосистемы «Вираж»: модули, методы, вебхуки — с примерами.

Обновлено: 18.11.2026

Единый вход на сайт клуба

Вход в личный кабинет авторизует болельщика и на сайте клуба. Логаут происходит на всех сайтах одновременно. Сеанс хранится на сервере платформы, в браузер уходит только идентификатор в cookie домена (.example.com), доступной всем поддоменам. CMS сайта значения не имеет: нужны два запроса, introspect и revoke.

Регистрация и восстановление пароля выполняются тем же API личного кабинета. Регистрация становится завершённой после подтверждения e-mail, а доменная SSO-сессия появляется только после последующего входа через POST /user/login с session: true.

Порядок вызовов

  • Новый болельщик: POST /user/registration, затем подтверждение e-mail через POST /user/email/verify.
  • Кабинет: POST /user/login с session: true. Платформа отвечает двумя cookie.
  • Кабинет: запросы к API с credentials: "include", без заголовка Authorization.
  • Сайт: читает cookie virazh_sso, вызывает POST /sso/introspect, получает профиль, ставит свою сессию.
  • Выход: кабинет вызывает POST /lk/auth/logout, сайт вызывает POST /sso/revoke.
Схема
браузер                 кабинет            платформа              сайт клуба
  |   логин/пароль  ----->   |                   |                       |
  |                          |-- POST /user/login ->                     |
  |<---- Set-Cookie: virazh_lk (crm.example.com) -|                      |
  |<---- Set-Cookie: virazh_sso (.example.com) ---|                      |
  |   открывает сайт  --------------------------------------------------> |
  |   (доменная cookie уходит сама)               |<- POST /sso/introspect
  |                          |                   |--- профиль ---------->|
  |<------------------ Set-Cookie: сессия сайта (.example.com) ---------- |

Методы

МетодПутьВызываетАвторизацияЛимит
POST/user/registrationкабинетнет10/мин
POST/user/email/send-verificationкабинетBearer-токен регистрации10/мин
POST/user/email/verifyкабинетBearer-токен регистрации10/мин
POST/user/loginкабинетнет10/мин
POST/reset-passwordкабинетнет10/мин
POST/reset-password/confirmкабинетreset token в теле10/мин
GET/sso/whoamiкабинетcookie или Bearer60/мин
POST/sso/introspectсервер сайтаX-Sso-Secret1200/мин
POST/sso/revokeсервер сайтаX-Sso-Secret60/мин
POST/sso/ticketкабинетcookie или Bearer20/мин
POST/sso/redeemсервер сайтаX-Sso-Secret60/мин
POST/lk/auth/logoutкабинетcookie или Bearerнет

Регистрация

POST /user/registration создаёт новый аккаунт или безопасно активирует уже импортированную карточку CRM без учётных данных. Активный личный аккаунт с тем же e-mail или телефоном перезаписать нельзя. Для личного кабинета следует передавать verification_channel: "email".

ПараметрТипОбязателенОписание
lastnamestringдаФамилия, до 255 символов
namestringдаИмя, до 255 символов
patronymicstringнетОтчество, до 255 символов
phonestringдаТелефон; кабинет отправляет нормализованное значение `+7…`
emailstringдаE-mail, приводится к нижнему регистру
passwordstringдаОт 6 до 72 символов, без пробелов
password_confirmationstringдаДолжен совпадать с `password`
birthdatedateнетДата рождения, не позднее текущей даты
genderstringнет`Мужской` или `Женский`
gender_idintegerнетИдентификатор пола из справочника; альтернатива полю `gender`
verification_channelstringнет`email` для кабинета; если поле не передано, используется SMS с резервом на e-mail
personal_data_consentbooleanдаСогласие на обработку персональных данных; принимается только `true`
marketing_consentbooleanнетСогласие на маркетинговые сообщения, по умолчанию `false`
Запрос и ответ
curl -X POST https://crm.example.com/api/v1/user/registration \
  -H 'Content-Type: application/json' \
  -d '{
    "lastname":"Иванов",
    "name":"Иван",
    "phone":"+79990001122",
    "email":"fan@example.com",
    "password":"secure-password",
    "password_confirmation":"secure-password",
    "verification_channel":"email",
    "personal_data_consent":true,
    "marketing_consent":false
  }'

# 200
{
  "data": {
    "user": { "id": 18422, "email": "fan@example.com", "is_active": false },
    "message": "…",
    "token": "18422|…"
  }
}

В ответ приходит временно используемый кабинетом Bearer-токен. Код подтверждения отправляет транзакционная цепочка CRM; срок действия кода — 60 минут. До успешного подтверждения аккаунт неактивен и обычный вход отклоняется.

Подтверждение e-mail
# Повторно отправить код
curl -X POST https://crm.example.com/api/v1/user/email/send-verification \
  -H 'Authorization: Bearer 18422|…' \
  -H 'Content-Type: application/json' \
  -d '{}'

# Подтвердить код
curl -X POST https://crm.example.com/api/v1/user/email/verify \
  -H 'Authorization: Bearer 18422|…' \
  -H 'Content-Type: application/json' \
  -d '{"code":"1234"}'
# → { "data": { "message": "Email успешно подтвержден." } }

После подтверждения кабинет выполняет обычный вход с session: true. Только этот шаг создаёт virazh_lk и virazh_sso; токен регистрации сам по себе доменную SSO-сессию не создаёт.

POST /user/login

Вход болельщика. С session: true создаёт сеанс и ставит cookie.

ПараметрТипОбязателенОписание
emailstringнетEmail, либо он, либо `phone`
phonestringнетТелефон в формате `+7…`
passwordstringдаПароль
sessionbooleanнетСоздать сеанс и поставить cookie
rememberbooleanнетДлинный сеанс, 30 суток
Ответ 200
Set-Cookie: virazh_lk=…; Path=/; Secure; HttpOnly; SameSite=Lax
Set-Cookie: virazh_sso=…; Domain=.example.com; Path=/; Secure; HttpOnly; SameSite=Lax

{
  "data": {
    "user": { "id": 18422, "name": "Иван", "lastname": "Иванов" },
    "token": "18422|…",
    "session": true
  }
}

session: false означает, что на платформе не задан SSO_COOKIE_DOMAIN. Токен в ответе есть всегда, по нему работают мобильное приложение и запасной путь через тикет.

Забыли пароль

POST /reset-password принимает e-mail и запускает транзакционную цепочку CRM. Ответ одинаков для существующего и неизвестного адреса, поэтому по методу нельзя проверить наличие аккаунта. Отправка письма выполняется асинхронно.

Запрос ссылки
curl -X POST https://crm.example.com/api/v1/reset-password \
  -H 'Content-Type: application/json' \
  -d '{"email":"fan@example.com"}'

# 200 для существующего и неизвестного адреса
{
  "message": "Если аккаунт с таким email существует, мы отправим инструкцию по восстановлению пароля."
}

Для существующего аккаунта CRM отправляет одноразовую ссылку вида https://my.example.com/login.html?reset_token=…. Токен зашифрован, по умолчанию действует 60 минут и становится недействительным после первого успешного использования, смены e-mail или изменения учётных данных.

ПараметрТипОбязателенОписание
tokenstringдаЗначение `reset_token` из ссылки
passwordstringдаНовый пароль: 6–72 символа, без пробелов
password_confirmationstringдаДолжен совпадать с `password`
Новый пароль
curl -X POST https://crm.example.com/api/v1/reset-password/confirm \
  -H 'Content-Type: application/json' \
  -d '{
    "token":"<reset_token из ссылки>",
    "password":"new-secure-password",
    "password_confirmation":"new-secure-password"
  }'

# 200
{ "message": "Пароль изменён. Теперь можно войти в личный кабинет." }
СтатусКогда возвращается
200Пароль изменён, аккаунт активирован
400Ссылка неверна, истекла или уже использована
422Пароль не прошёл проверку или подтверждение не совпало
429Превышен лимит 10 запросов в минуту

После успешного сброса CRM отзывает все API-токены и серверные сессии пользователя. Кабинет удаляет reset_token из адресной строки и предлагает войти заново; новый SSO-сеанс создаётся только новым вызовом POST /user/login.

GET /sso/whoami

Проверка сеанса кабинетом: 200 с профилем, если cookie принята, 401 если нет.

Ответ 200
{
  "data": {
    "session": true,
    "user": { … тот же профиль, что отдаёт introspect … }
  }
}

POST /sso/introspect

Профиль по доменной cookie. Вызывает сервер сайта, ключ в заголовке.

Запрос
curl -X POST https://crm.example.com/api/v1/sso/introspect \
  -H 'X-Sso-Secret: <ключ сайта>' \
  -H 'Content-Type: application/json' \
  -d '{"id":"<значение cookie virazh_sso>"}'
Ответ 200
{
  "data": {
    "remember": true,
    "expires_at": 1793000000,
    "user": {
      "id": 18422,
      "email": "fan@example.com",
      "phone": "+79990001122",
      "name": "Иван",
      "lastname": "Иванов",
      "patronymic": null,
      "display_name": "Иван Иванов",
      "avatar": "https://crm.example.com/storage/avatars/18422.webp",
      "points": 2400,
      "loyalty_level": {
        "id": 2,
        "name": "Золотой"
      }
    }
  }
}

В CRM «Шанхай Дрэгонс» профиль в ответах GET /sso/whoami, POST /sso/introspect и POST /sso/redeem содержит loyalty_level: объект с идентификатором id и названием name текущего уровня программы лояльности. Если уровень не назначен, значение равно null. В других клубных CRM доступность поля зависит от версии.

СтатусЗначение
200Сеанс жив, профиль отдан
401Ключ не совпал
410Сеанс истёк, погашен, аккаунт отключён, изменился пароль, либо значение не похоже на идентификатор
503На платформе не заданы ключи потребителей

POST /sso/revoke

Гасит сеанс целиком. Вызывается сайтом при выходе, после этого кабинет получает 401.

Запрос
curl -X POST https://crm.example.com/api/v1/sso/revoke \
  -H 'X-Sso-Secret: <ключ сайта>' \
  -H 'Content-Type: application/json' \
  -d '{"id":"<значение cookie virazh_sso>"}'
# → { "data": { "revoked": true } }

POST /sso/ticket и /sso/redeem

Запасной путь для сайта на другом домене второго уровня, куда доменная cookie не доходит. Тикет живёт 120 секунд и гаснет при первом обмене, повторный даёт 410. Кабинет передаёт его фоновым запросом или переходом на https://сайт/?virazh_sso=<тикет>.

Параметр ticketТипОбязателенОписание
audiencestringнетПолучатель тикета, до 32 символов; неизвестное значение заменяется первым разрешённым
rememberbooleanнетПередать признак длинной сессии
statestringнет64 hex-символа для привязки входа к браузеру получателя

Для магазина state обязателен на уровне сценария: магазин генерирует случайное значение, кабинет включает его в тикет, а при обмене магазин сравнивает возвращённый state со значением в браузере. Несовпадение нельзя превращать в сессию.

Выдача и обмен
curl -X POST https://crm.example.com/api/v1/sso/ticket \
  -H 'Authorization: Bearer <токен болельщика>' \
  -H 'Content-Type: application/json' \
  -d '{"audience":"site","remember":true}'
# → { "data": { "ticket": "9f1c…64 hex…a7", "expires_in": 120 } }

curl -X POST https://crm.example.com/api/v1/sso/redeem \
  -H 'X-Sso-Secret: <ключ сайта>' \
  -H 'Content-Type: application/json' \
  -d '{"ticket":"9f1c…a7"}'
# → профиль, как у introspect, плюс audience и remember

Cookie

CookieДоменЧитаетНазначение
virazh_lkдомен платформыплатформаАвторизация запросов кабинета к API
virazh_sso.example.comсайт, платформаИдентификатор сеанса для интроспекции

Обе cookie помечены HttpOnly, Secure, SameSite=Lax. virazh_sso видят все поддомены, поэтому доступа к API она не даёт: по ней можно только получить профиль, предъявив ключ. Без «Запомнить меня» обе cookie сеансовые, срок держит серверная запись: SSO_SESSION_LIFETIME, 120 минут, продлевается при обращениях кабинета и сайта.

Ключ сайта: заголовок X-Sso-Secret. У каждого потребителя он свой — платформа держит их списком SSO_CLIENT_KEYS вида site:ключ,shop:ключ, и утёкший ключ отзывается поимённо, не выбивая остальных. Выпускается командой openssl rand -hex 32, в браузер не передаётся.

Переменные платформы

ПеременнаяПо умолчаниюНазначение
SSO_CLIENT_KEYSпустоКлючи потребителей: `site:ключ,shop:ключ`. Пусто: `introspect` и `redeem` отдают 503
SSO_SHARED_SECRETпустоОбщий ключ прежней схемы. Работает под именем `shared`, пока не убран
SSO_COOKIE_DOMAINпустоДомен cookie и выключатель схемы. Пусто: только запасной путь
SSO_SESSION_LIFETIME120Минут, обычный сеанс
SSO_SESSION_REMEMBER_LIFETIME43200Минут, сеанс с «Запомнить меня»
SSO_ALLOWED_ORIGINSпустоOrigin, которым разрешены изменяющие запросы по cookie. Пусто: берётся `CORS_ALLOWED_ORIGINS`
SSO_COOKIE_SECUREtrueФлаг `Secure` у cookie
SSO_TICKET_TTL120Секунд, срок жизни тикета
SSO_API_COOKIEvirazh_lkИмя cookie кабинета
SSO_IDENTITY_COOKIEvirazh_ssoИмя доменной cookie

Подключение сайта

На запросе страницы: прочитать virazh_sso, вызвать introspect, авторизовать пользователя. При выходе: вызвать revoke. Пользователь сайта ищется по идентификатору болельщика, затем по email и телефону. Ответ интроспекции кешируется на 2–5 минут по хэшу cookie. Статус 410 означает выход, таймаут и 429 состояние сессии не меняют. Cookie сессии сайта ставится на домен .example.com.

Профиль по cookie
function virazhSsoProfile(): array|string|null
{
    $id = $_COOKIE['virazh_sso'] ?? '';
    if (preg_match('/^[a-f0-9]{64}$/', $id) !== 1) {
        return null;      // cookie нет: гость
    }

    $ch = curl_init('https://crm.example.com/api/v1/sso/introspect');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 8,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Sso-Secret: ' . SSO_KEY],
        CURLOPT_POSTFIELDS => json_encode(['id' => $id]),
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code === 410) {
        return null;      // сеанса нет: разлогинить
    }
    if ($code !== 200) {
        return 'unknown'; // таймаут, 429, 5xx: сессию не трогать
    }

    return json_decode($body, true)['data']['user'];
}

Домен cookie сайта задаётся аргументом domain у setcookie(): .example.com.

Сторона кабинета

Вход и запросы
const res = await fetch(API + '/user/login', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, password, session: true, remember }),
}).then((r) => r.json());

// cookie принята браузером?
const cookieWorks = await fetch(API + '/sso/whoami', {
  credentials: 'include',
}).then((r) => r.ok);

await fetch(API + '/lk/dashboard', { credentials: 'include' });

cookieWorks: false означает запасной путь: токен из ответа плюс тикет. Проверку ограничить тремя секундами. Изменяющие запросы по cookie принимаются только с Origin из SSO_ALLOWED_ORIGINS, иначе 401.

Диагностика

СимптомПричина
`session: false` при входеНе задан `SSO_COOKIE_DOMAIN`
Сайт считает гостемСтраничный кеш отдаёт страницу гостя
Сайт не видит cookieКабинет и сайт на разных доменах второго уровня
Гость на соседнем поддоменеСессия сайта поставлена на хост
`POST` даёт 401, `GET` работаетOrigin кабинета не в `SSO_ALLOWED_ORIGINS`, отказ пишется в лог
`401` на интроспекцииКлючи на сайте и платформе разошлись
`410` на интроспекцииСеанс погашен или истёк, сайту следует разлогинить

Ограничения

  • Направление одно: вход на сайте сеанс в кабинете не создаёт.
  • Вход по SMS-коду доменной сессии не создаёт, только токен.
  • Аккаунты с правами редактирования через единый вход не авторизуются.
  • Смена ключа нужна одновременно на платформе и на сайте, в промежутке интроспекция отдаёт 401.
  • Пароль пользователю, созданному единым входом, ставится случайный.