Әзірлеушілер порталы және қол жеткізу токендері

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 (қосымша деңгей)

ingress бойынша өзара TLS; сертификаттар портал арқылы жүктеледі; 'cert _ fingerprint' тіркемесі.

4) Токендер: типтері және тіршілік циклі

• Қысқа АТ + ұзын 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

'token _ store' (Redis/SQL) Auth-серверінде сақтаңыз.
Интроспекция: '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

SDK авто генерациясы бар OpenAPI/AsyncAPI.
Cookbook: сұрау мысалдары, ретра, теңсіздік, пагинация, webhooks.
Try-it playground (құм кілттерімен).
Changelog нұсқасы және депрекация беті.

9) Құмсалғыш және тестілік деректер

Оқшауланған орталар: 'sandbox', 'staging', 'production'.
Тест мәні (ойыншылар, транзакциялар) және сценарийлер (win/lose, кідірістер, 5xx, 429).
Порталдан және қоршаудан Data seeding.

10) Қауіпсіздік және құпияларды сақтау

API Key құпия хеші (ашық күйде сақталмайды); кілтті бір рет көрсету.
Қолтаңба белгілеріне арналған құпия менеджері (KMS/HSM); kid кілттерін ауыстыру.
IP allowlist, гео-шектеулер, ASN-сүзгілер.
2FA/SSO, аппараттық кілттер (WebAuthn).
Абьюздан қорғау: CAPTCHA құру кезінде, эвристикаға қарсы бот, тіркеу жылдамдығы.
PII/құпиясыз логтар; үлгілер бойынша redaction.

11) Аудит және сәйкестiк

Аудит-лог: кілтті кім құрды/қарап шықты/қайтарып алды, вебхукті өзгертті, есепті жүктеп алды.
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-bot/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, сенімді веб-хактар мен аудитті беріңіз. Сонда интеграторлар тез іске қосылады, ал сіздің платформаңыз басқарылатын, комплаентті және жүктеме астында тұрақты болып қалады.