Аутентификация

API кілттері (интеграциялар үшін ұсынылады)

API кілті - аккаунтыңыздың мүшесіне байланған жеке қол жеткізу токені.

Кілтті Баптаулар → Плагиндер → RolChat API кілттері бөлімінде жасаңыз. Құпия бір рет көрсетіледі; одан кейін тек алғашқы он таңбасы көрінеді, ал RolChat тек SHA-256 хешін сақтайды.
Пішім: rcp_, одан кейін base64url түріндегі 32 кездейсоқ байт, барлығы шамамен 45 таңба. Префикс кілтті логтарда тануға және оны сессия токенінен ажыратуға мүмкіндік береді.
Қол жеткізу аймақтары: кілт жасалған кезде мүмкіндіктердің тұрақты каталогынан таңдалады. Кілт оны жасаған мүшеден артық ештеңе істей алмайды: әр шақыруда екі шарт та тексеріледі - мүмкіндік кілттің аймақтарына кіреді және мүшеде ол әлі де бар. Мүшенің рөлін тарылтсаңыз, кілт те бірге тарылады.
Жарамдылық мерзімі: кілттердің мерзімі өздігінен бітпейді. Кілтті профиль бетінде немесе DELETE /api/v1/tokens/:id арқылы кері қайтарып алыңыз; бұл бірден күшіне енеді. Орнында ротация жоқ: кілтті кері қайтарып, жаңасын жасаңыз.
Жасау және кері қайтарып алу аудит журналына жазылады.

Кілтті bearer токені ретінде жіберіңіз - API кілтіне арналған бөлек тақырып жоқ:

curl https://api.rolchat.com/api/v1/contacts?limit=20 \
  -H "Authorization: Bearer rcp_…" \
  -H "X-Account-Id: 7c1d2c6e-…"

Плагиннің API кілті бар сұраулар минутына 300-мен шектелген.

JWT сессиялары

Веб-қолданба мен мобильді SDK электрондық пошта мен құпиясөз арқылы (немесе Google не Apple арқылы) кіріп, токендер жұбын алады.

Токен	Жарамдылық мерзімі	Ескертпелер
Access токені	15 минут	RS256, `/.well-known/jwks.json` мекенжайындағы JWKS бойынша тексеріледі
Refresh токені	30 күн	Әр жаңартуда ауыстырылады; ауыстырылған токенді қайта пайдалану бүкіл тізбекті кері қайтарады

Мәлімдемелер (claims): sub (пайдаланушы), acc (аккаунт), rl (рөл) және сайт деңгейіндегі рөлдер үшін sts (рұқсат етілген сайттар).

POST /auth/login, /auth/refresh, /auth/swap-company және /auth/logout - төменде сипатталған X-Account-Id тақырыбын жібермеуі тиіс жалғыз аутентификация эндпоинттері.

`X-Account-Id` тақырыбы

Жоғарыдағы төртеуінен басқа әр аутентификацияланған сұрау қай аккаунттың атынан орындалатынын көрсетуі керек:

X-Account-Id: <account uuid>

Сервер тақырыптың токендегі acc мәлімдемесіне (немесе API кілтінің аккаунтына) тең екенін тексереді. Тақырып жоқ болса, 400 missing_required_header, сәйкес келмесе, 403 account_context_mismatch қайтарылады. Тақырып клиенттегі қате немесе қайта жіберілген токен басқа клиенттің деректерін ешқашан байқаусыз оқи алмауы үшін қажет: сәйкессіздік деректерге кез келген сұрау орындалмай тұрып қабылданбайды, ал логтың әр жолын токенді декодтамай-ақ аккаунтқа жатқызуға болады.

Бірнеше компаниядағы пайдаланушылар

Бір адам бірнеше компанияның мүшесі бола алады. Әр компанияның өз токені (өз acc мәлімдемесі) бар. Ауысу үшін:

POST /api/v1/auth/swap-company
Authorization: Bearer <current access token>

{ "account_id": "<target uuid>" }

Мақсатты компания шақырушының available_companies тізімінде (кіру кезінде қайтарылады) болуы керек, әйтпесе 403 forbidden қайтарылады. Жауап ретінде мақсатты компанияға арналған жаңа access және refresh токендер жұбы келеді; ескі refresh токені кері қайтарылады және auth.account.swapped аудит оқиғасы жазылады.

Көпфакторлы аутентификация

TOTP негізіндегі MFA-ны әр мүше үшін қосуға және бүкіл аккаунт үшін міндетті етуге болады. Ол қосулы болса, POST /auth/login растау сұрауын қайтарады, ал сессия POST /auth/mfa/verify арқылы аяқталады. Резервтік кодтар қосу кезінде беріледі.

Кіруді қорғау

Кіру маршруттары бір IP-ден минутына 10 әрекетпен және бір электрондық поштадан 15 минутта 5 әрекетпен шектелген.
Он сәтсіз кіру әрекеті электрондық поштаны 30 минутқа бұғаттайды; жауапта code: account_locked болады.
reCAPTCHA-ны жекелеген әрекеттер үшін (тіркелу, кіру, құпиясөзді қалпына келтіру) қосуға болады; жария бастапқы конфигурация GET /api/v1/captcha арқылы беріледі.