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

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, надійні вебхуки і аудит. Тоді інтегратори швидко стартують, а ваша платформа залишиться керованою, комплаєнтною і стійкою під навантаженням.