API: Auth

Эндпоинты аутентификации MeerPartners: обмен MeerID, ротация и отзыв токенов, S2S token-exchange, активация партнёра и создание бизнеса.

Группа /api/v1/auth/* отвечает за вход людей и онбординг ролей. Вход — только через MeerID (единый OIDC SSO): email/пароля/OTP нет. Базовые механизмы и подпись HMAC описаны на странице Аутентификация.

POST /auth/meerid/exchange

Первая сессия: обмен результата авторизации MeerID на локальную JWT-пару. Поддерживает два потока — popup/redirect (по code + PKCE) и FedCM (по idToken). Передавайте поля ровно одного потока.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6...",
  "token_type": "bearer",
  "expires_in": 900,
  "meerid_id_token": "eyJhbGciOiJSUzI1NiIs...",
  "user": {
    "user_id": 1042,
    "email": "creator@example.com",
    "display_name": "Аня",
    "is_affiliate": true,
    "affiliate_id": 88,
    "memberships": [
      { "tenant_id": 17, "role": "merchant_owner" }
    ]
  }
}

expires_in — TTL access-токена в секундах (900 = 15 минут). meerid_id_token нужен BFF-у как id_token_hint при выходе через MeerID (только в popup-флоу; FedCM его не выдаёт). Лимит: 20 запросов в минуту на IP — см. Лимиты.

Ошибки: MEERID_TOKEN_ERROR (401), MEERID_IDTOKEN_INVALID (401), MEERID_IDTOKEN_NONCE (401), MEERID_ACCESS_DENIED (403 — бан/удаление), MEERID_USERINFO_ERROR (401), MEERID_UNAVAILABLE (502), RATE_LIMIT_EXCEEDED (429).

POST /auth/refresh

Ротация refresh-токена: возвращает новую пару, старый refresh помечается использованным (одноразовый, с grace-окном на гонку параллельных рефрешей). Если у пользователя привязан MeerID refresh — платформа параллельно проверяет его и при бане/удалении аккаунта отзывает все локальные сессии.

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 900
}

Ошибки: TOKEN_WRONG_TYPE (401), TOKEN_REVOKED (401), TOKEN_EXPIRED (401), TOKEN_INVALID (401), ACCESS_REVOKED (401 — аккаунт MeerID заблокирован/удалён).

POST /auth/logout

Отзыв текущей сессии (конкретного refresh-JTI). Access-токен доживает свой TTL. Идемпотентно: невалидный/уже отозванный токен всё равно вернёт успех.

{ "message": "Выход выполнен" }

POST /auth/logout-all

Отзыв всех сессий пользователя. Требует полный (не embed-scoped) токен.

{ "message": "Отозвано сессий: 3" }

Ошибки: EMBED_SCOPE_DENIED (403 — вызвано scoped embed-токеном).

POST /auth/token-exchange

S2S-обмен (RFC 8693-style): сервер бизнеса меняет внешний идентификатор своего пользователя на scoped affiliate-токен для embed-SDK. Аутентификация — подпись tenant_api_key со скоупом sso. tenant_id берётся только из ключа в БД; одноимённое поле в теле игнорируется (анти-IDOR).

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 600,
  "scope": "affiliate:embed",
  "affiliate_id": 88,
  "tenant_id": 17
}

Scoped-токен (scope: affiliate:embed, TTL 10 минут) даёт доступ только к чтению данных своего affiliate_id в группе Affiliate; мутации профиля/KYC и методов вывода через него запрещены.

Ошибки: TENANT_API_KEY_INVALID (401), TENANT_API_KEY_SCOPE_DENIED (403), EXCHANGE_DENIED (401), EXCHANGE_REPLAY (401), USER_BANNED (403), SERVICE_UNAVAILABLE (503).

POST /auth/affiliate/activate

Явный шаг «стать партнёром»: создаёт affiliate-профиль для текущего пользователя. Идемпотентно — повторный вызов вернёт тот же профиль. Требует полный Bearer-токен.

{ "message": "Партнёрский профиль активирован (affiliate_id=88)" }

Ошибки: UNAUTHORIZED (401), EMBED_SCOPE_DENIED (403).

POST /auth/merchant/create-business

Атомарная регистрация бизнеса: создаёт tenant + аккаунт мерчанта + нулевой эскроу-баланс + членство merchant_owner в одной транзакции. Личность берётся из Bearer-токена (без email/OTP). Требует полный токен.

{
  "tenant_id": 17,
  "tenant_slug": "acme",
  "merchant_account_id": 21,
  "role": "merchant_owner",
  "message": "Бизнес создан."
}

Ошибки: TENANT_SLUG_TAKEN (409 — slug занят), VALIDATION_ERROR (422), USER_NOT_FOUND (404).

Что дальше