External Partner API¶

LMS-платформы могут получать данные пользователей Flawbusters (профиль, статистику, Security Matrix, достижения) через External Partner API. Пользователь явно даёт согласие на передачу данных через OAuth consent screen.

Полный справочник: API Reference.

Модель доверия¶

OAuth 2.0 Authorization Code + PKCE — для линковки конкретного пользователя.
HMAC-SHA256 — для всех server-to-server запросов после линковки.

Регистрация партнёра¶

Администратор Flawbusters создаёт партнёра через Admin API и передаёт вам один раз:

client_id — публичный идентификатор.
client_secret — для OAuth token exchange.
hmac_secret — для HMAC-подписи запросов.

Секреты показываются один раз

client_secret и hmac_secret не могут быть восстановлены. Храните их в secure vault (AWS Secrets Manager, Vault, GCP Secret Manager).

Линковка пользователя (OAuth 2.0 + PKCE)¶

Шаг 1. PKCE challenge¶

```python import base64, hashlib, secrets

verifier = secrets.token_urlsafe(64) # 43–128 символов challenge = base64.urlsafe_b64encode( hashlib.sha256(verifier.encode()).digest() ).rstrip(b"=").decode() ```

Шаг 2. Authorize¶

Перенаправьте пользователя:

GET https://flawbusters.com/api/v1/oauth/authorize ?client_id={client_id} &redirect_uri={redirect_uri} &response_type=code &scope=profile:read &state={random_state} &code_challenge={challenge} &code_challenge_method=S256

Пользователь увидит consent screen с запрашиваемыми scope и подтвердит доступ.

Шаг 4. Callback¶

Flawbusters перенаправит обратно:

{redirect_uri}?code={code}&state={state}

Проверьте state — он должен совпадать с отправленным.

Шаг 5. Обмен кода на токены¶

```http POST /api/v1/oauth/token Content-Type: application/x-www-form-urlencoded Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code &code={code} &redirect_uri={redirect_uri} &code_verifier={verifier} ```

Ответ содержит external_user_id — opaque-идентификатор пользователя в вашей системе. Сохраните его.

Server-to-server запросы (HMAC)¶

Для всех запросов к External API используйте HMAC-SHA256.

Заголовки¶

Заголовок	Значение
`X-Partner-Key`	`client_id`
`X-Timestamp`	Unix timestamp (сек), отклонение от серверного — не более 5 минут
`X-Nonce`	Случайный UUID для защиты от replay
`X-Signature`	HMAC-SHA256 от `method\npath\ntimestamp\nnonce\nbody_sha256`, hex

Пример подписи (Python)¶

```python import hashlib, hmac, time, uuid

method = "GET" path = "/api/v1/partner/users/{external_user_id}/profile" timestamp = str(int(time.time())) nonce = str(uuid.uuid4()) body = b"" body_sha = hashlib.sha256(body).hexdigest()

message = f"{method}\n{path}\n{timestamp}\n{nonce}\n{body_sha}" signature = hmac.new( hmac_secret.encode(), message.encode(), hashlib.sha256 ).hexdigest() ```

Доступные endpoints¶

Endpoint	Описание
`GET /partner/users/{id}/profile`	Публичный профиль пользователя
`GET /partner/users/{id}/stats`	Статистика: решения, активность, время
`GET /partner/users/{id}/security-matrix`	Security Matrix по всем категориям
`GET /partner/users/{id}/achievements`	Список полученных ачивок

Полная спецификация, схемы ответов, коды ошибок — в API Reference.

Best practices¶

Храните external_user_id как основной ключ связки — он стабилен.
Не полагайтесь на email: пользователь может его сменить.
Проверяйте exp и iat JWT-ответов, если используете их для сессий.
Соблюдайте X-Timestamp в пределах 5 минут и не переиспользуйте X-Nonce.
Обрабатывайте 429 Too Many Requests с экспоненциальным backoff.

Отзыв согласия¶

Пользователь может отозвать согласие в настройках Flawbusters. После этого все партнёрские запросы по его external_user_id вернут 403 Forbidden. Обрабатывайте это как мягкую деактивацию связки, не блокирующую работу LMS.