Портал разработчиков и токены доступа

1) Роль портала разработчиков

Developer Portal — это «фронт-офис» для интеграторов: самообслуживание (ключи, токены, вебхуки, планы тарифов), прозрачность (лимиты, usage, инвойсы), безопасность (ротация, подписи), скорость интеграции (SDK, документация, песочница).

• Сократить TTI (time-to-integrate) до часов.
• Дать управляемость доступа: кто/что/сколько/когда.
• Снизить нагрузку на поддержку через авто-инструменты.

2) Онбординг и учетные записи

Регистрация: email + 2FA/SSO (SAML/OIDC); подтверждение домена (DNS-токен).
Организации и команды: роли `Owner`, `Admin`, `Developer`, `Billing`, `Security`.
Мульти-тенант: привязка приложений к организациям; доступ к данным — по тенанту/окружению.
KYC/B2B (опц.): для Enterprise — юридическое лицо, договор, лимиты выше.

3) Приложения и креденшелы

Типы приложений: `server-to-server`, `web`, `mobile`, `machine-to-machine`, `webhook-consumer`.

3.1 API Keys (server-to-server, простые интеграции)

Идентификатор `key_id` + секрет `key_secret` (виден один раз).
Привязка к плану и наборам scopes.
Подпись запросов (HMAC) и/или заголовок `Authorization: ApiKey <key_id>:<signature>`.

3.2 OAuth2 / OIDC (рекомендуется)

• Client Credentials (машины).
• Authorization Code (+PKCE) (user-delegated).
• Refresh Token (офлайновый доступ, ротация RT).
• Device Code (TV/консоли).

3.3 mTLS (доп. уровень)

Взаимная TLS на ingress; сертификаты загружаются через портал; привязка `cert_fingerprint` к приложению.

4) Токены: типы и жизненный цикл

• Короткий AT + длинный RT; RT — скользящая ротация (rotate-on-use).
• Принудительный отзыв (revoke) по ключу/приложению/организации.
• Пере-выдача с сохранением ограничений по scopes/квотам.

4.1 Формат JWT (пример)

json
{
"iss":"https://auth. example. com",
"sub":"app_123",
"aud":"https://api. example. com",
"exp":1730616000,
"iat":1730612400,
"scp":["wallet:read","bet:write"],
"org":"acme",
"kid":"jwks_2025_11",
"jti":"at_01HXY..."
}

Публичные ключи публикуются в JWKS; ротация по `kid`.

4.2 Opaque токены и Introspection

Храните в Auth-сервере `token_store` (Redis/SQL).
Интроспекция: `active`, `scope`, `exp`, `client_id`, `org`, `tenant`.

5) Scopes, роли и политики доступа

Scopes описывают операции (`wallet:read`, `wallet:write`, `report:read`).
Роли агрегируют scopes (`Developer`, `Billing`).
ABAC: атрибуты `org`, `tenant`, `region`, `environment`.
Политики: «этот ключ — только `eu-west-1` и `read`».
Step-up: для критичных методов требуются расширенные scopes или mTLS.

6) Квоты, лимиты и тарифы

Rate limits: RPS/RPM, burst.
Квоты: день/месяц, кредиты.
По ключу/приложению/организации/тенанту.
Портал показывает usage, заголовки `X-RateLimit-` и `X-Quota-`, а также прогноз overage.
Биллинг: связка с планом, метеринг по событиям, инвойсы и вебхуки биллинга.

7) Управление вебхуками

Регистрация endpoint’ов, секретов, версий событий.
Тест-доставка и replay; логи попыток (2xx/4xx/5xx).
Подписи HMAC (`X-Signature`), `X-Webhook-Id`, дедупликация, respect `410`.

8) Документация и SDK

OpenAPI/AsyncAPI с авто-генерацией SDK.
Cookbook: примеры запросов, ретраи, идемпотентность, пагинация, webhooks.
Try-it playground (с песочными ключами).
Версионный Changelog и страница депрекаций.

9) Песочница и тестовые данные

Изолированные окружения: `sandbox`, `staging`, `production`.
Тестовые сущности (игроки, транзакции) и сценарии (win/lose, задержки, 5xx, 429).
Data seeding из портала и reset окружения.

10) Безопасность и хранение секретов

Хэш секретов API Key (не хранить в открытом виде); показать ключ один раз.
Менеджер секретов (KMS/HSM) для токенов подписи; ротация ключей `kid`.
IP allowlist, гео-ограничения, ASN-фильтры.
2FA/SSO, аппаратные ключи (WebAuthn).
Защита от абьюза: CAPTCHA при создании, анти-бот эвристики, скорость регистрации.
Логи без PII/секретов; redaction по шаблонам.

11) Аудит и соответствие

Аудит-лог: кто создал/просмотрел/отозвал ключ, изменил вебхук, скачал отчет.
GDPR/DSAR: выгрузка и удаление данных приложения/организации.
Политики хранения: TTL для логов, Legal Hold при инцидентах.
Terms of Use/Fair Use и экспортные ограничения.

12) Администрирование и операции

Массовый отзыв токенов по инциденту/компрометации.
Временная приостановка приложения (suspend) с причиной и апелляцией.
Ролл-овер ключей (двухключевой режим: `active/next`).
Инцидент-комм: статус-страница, рассылки, RSS/вебхуки статуса.

13) UI/UX портала (ключевые экраны)

Дашборд организации: usage/ошибки/SLO/биллинг.
Приложение: ключи, токены, scopes, лимиты, вебхуки, окружения.
Логи доставки вебхуков с фильтрами и кнопкой Replay.
Токен-консоль: выпуск/отзыв, история, причины.
Документация и SDK, Quickstart, примеры кода (копировать-вставить).
Раздел «Депрекации и миграции».

14) Примеры контрактов и конфигов

14.1 OpenAPI (фрагменты)

yaml paths:
/v1/apps:
post:
summary: Create app security: [{ oauth2: [admin:apps. write] }]
responses:
'201': { description: Created }
/v1/apps/{app_id}/keys:
post:
summary: Create API key (shown once)
responses:
'201': { description: Created }
/v1/oauth2/token:
post:
summary: Token endpoint (CC/AC)
responses:
'200': { description: Access token }
/v1/tokens/revoke:
post:
summary: Revoke access/refresh token responses:
'204': { description: Revoked }

14.2 Интроспекция токена (ответ)

json
{
"active": true,
"client_id": "app_123",
"scope": "wallet:read bet:write",
"org": "acme",
"exp": 1730616000,
"token_type": "access_token",
"jti": "at_01HXY..."
}

14.3 Политика ключей (JSON)

json
{
"app_id":"app_123",
"plan":"pro-2025",
"scopes":["wallet:read","report:read"],
"limits":{"rps":50,"daily_requests":250000},
"regions":["eu-west-1"],
"ip_allow":["192. 0. 2. 0/24"]
}

15) Процессы версионирования и депрекаций

Семантические версии API (`/v1`, `/v2`), совместимость «добавляй, не ломай».
Портал показывает: «что устаревает», до какой даты, и «как мигрировать».
Миграционные гиды, тест-песочница `v2`, dual-write/dual-read где возможно.

16) Наблюдаемость и отчетность

Usage → выручка: графики запросов/кредитов/овериджей.
Ошибки по статусам/`error_code`, гистограммы латентности.
SLO-виджеты: доступность и p95 для ключевых ручек.
Экспорт CSV/JSON, вебхуки отчетов, API для аналитики.

17) Чек-листы

17.1 Безопасность

• 2FA/SSO, подтверждение домена/почты
• Показ секретов один раз, хэш-хранение
• JWKS и ротация ключей, `kid`
• mTLS (опц.), IP allowlist, geo/ASN фильтры
• Анти-бот/anti-abuse, rate-limit на создание ключей
• Аудит-лог действий и доступов

17.2 DX/Онбординг

• Quickstart ≤ 5 минут
• SDK (TS/Py/Java/Go/.NET) с одинаковой поверхностью
• Playground + песочные ключи
• Cookbook: вебхуки, пагинация, ретраи, идемпотентность
• Страница лимитов/планов/цен
• Примеры «копировать-вставить»

17.3 Операции

• Массовый отзыв токенов, suspend app
• Страница инцидентов/статуса + подписка
• DLQ/Replay для вебхуков
• Авто-оповещения о близком исчерпании квот
• Ежемесячные отчеты и инвойсы

18) План внедрения (3 итерации)

• Регистрация орг/приложений, выдача API Keys, Client Credentials OAuth2, базовые лимиты (RPS/квоты), логи запросов и usage-графики, документация и SDK TS/Python, песочница.

• JWT + JWKS, ротация ключей, Refresh Token + rotate-on-use, мандатная 2FA/SSO, вебхуки (подписи, retries, логирование, replay), биллинг-вебхуки, отчеты и экспорт, роли и ABAC.

• mTLS, админ-инструменты (mass revoke/suspend), депрекации и миграции v2, SDK Java/Go/.NET, финопс-дашборды, GDPR/DSAR, Legal Hold, продвинутая анти-абьюз.

19) Мини-FAQ

JWT или opaque?
JWT удобен без запроса к Auth-серверу (подпись/`kid`), opaque — проще отзывать и скрывает содержимое. Часто используют оба: внешне JWT, внутренне — opaque с интроспекцией.

Сколько живет Access Token?
Коротко: 5–15 минут для пользовательских, 15–60 минут для машинных. Компенсируется refresh-механикой.

Как безопасно ротировать ключи?
Держите `active/next`, публикуйте оба в JWKS, переключайте клиентов по `kid`, затем отзывать старый.

Итог

Сильный портал разработчиков — это самообслуживание, наблюдаемость и безопасность по умолчанию. Дайте понятные процессы выпуска/ротации/отзыва токенов, прозрачные лимиты и биллинг, качественную документацию и SDK, надежные вебхуки и аудит. Тогда интеграторы быстро стартуют, а ваша платформа останется управляемой, комплаентной и устойчивой под нагрузкой.