Токен түрлері

HitKey бірнеше түрлі токендерді пайдаланады. Айырмашылықты түсіну дұрыс интеграция үшін маңызды.

OAuth2 токендер

Бұлар OAuth2 ағыны арқылы шығарылады және пайдаланушы атынан HitKey API-ге қол жеткізу үшін пайдаланылады.

Access Token

Қасиет	Мәні
Мерзімі	1 сағат
Қолданылуы	Authorization: Bearer <token> тақырыбы
Эндпоинт	/oauth/userinfo
Алу жолы	/oauth/token (код айырбастау немесе жаңарту)

Access токендер қысқа мерзімді. Бірі аяқталғанда, жаңасын алу үшін refresh токенді пайдаланыңыз.

Refresh Token

Қасиет	Мәні
Жылжымалы терезе	30 күн (әр пайдаланғанда қалпына келеді)
Абсолютті шек	90 күн (максималды мерзім)
Қолданылуы	POST /oauth/token grant_type=refresh_token мәнімен
Ротация	Жоқ — сол refresh токен жарамды болып қалады

INFO

OAuth refresh токендер ротацияланбайды — сол refresh токенді мерзімі аяқталғанша қайта пайдалануға болады. Тек access токен жаңартылады.

Бұл API Bearer токенді жаңартудан (POST /auth/token/refresh) ерекшеленеді, ол refresh токенді ротациялайды.

Authorization Code

Қасиет	Мәні
Мерзімі	10 минут
Қолданылуы	Бір реттік, access + refresh токенге айырбасталады
Ағыны	Пайдаланушы авторизациясынан кейін redirect арқылы алынады

API Bearer токендер

Бұлар HitKey-дің ішкі аутентификация токендері, тікелей API қолжетімділік үшін пайдаланылады (OAuth2 емес).

Қасиет	Мәні
Шығарылу жолы	POST /auth/login
Префикс	hitkey_
Қолданылуы	Authorization: Bearer <token> тақырыбы
Эндпоинттер	Барлық /auth/*, /projects/*, /oauth/clients
Жаңарту	POST /auth/token/refresh — refresh токенді ротациялайды

Қайсысын қашан пайдалану

• OAuth2 токендер — сіздің қосымшаңыз пайдаланушы атынан HitKey-ге кірген кезде (стандартты серіктес интеграция)
• API Bearer токендер — пайдаланушы HitKey-мен тікелей әрекеттескенде (HitKey бақылау тақтасы осыларды пайдаланады)

Серіктес әзірлеуші ретінде сіз негізінен OAuth2 токендермен жұмыс істейсіз.

Токенді сақтау ұсыныстары

Токен	Қайда сақтау	Ескертулер
Access token	Жад немесе қауіпсіз сақтау	Қысқа мерзімді, қайта алуға болады
Refresh token	Сервер жағындағы қауіпсіз сақтау	Ешқашан фронтендке көрсетпеңіз
Client secret	Орта айнымалысы	Ешқашан кодта немесе фронтендте

Токен қауіпсіздігі

• Авторизация кодтары сақталар алдында хэштеледі (SHA-256) — API тек хэшті сақтайды
• Access және refresh токендер де хэш ретінде сақталады
• Ашық мәтіндегі токендер тек жасалған кезде бір рет қайтарылады
• Токен айырбастау client_id мен client_secret екеуін де талап етеді