Autentifikasiya

API açarları (inteqrasiyalar üçün tövsiyə olunur)

API açarı hesabınızın üzvünə bağlı şəxsi giriş tokenidir.

• Onu Parametrlər → Plaginlər → RolChat API açarları bölməsində yaradın. Gizli dəyər bir dəfə göstərilir; sonra yalnız ilk on simvolu görünür, RolChat isə yalnız SHA-256 hash-ını saxlayır.
• Format: rcp_ və ardınca base64url formatında 32 təsadüfi bayt, cəmi təxminən 45 simvol. Prefiks açarı loglarda tanınan və sessiya tokenindən fərqlənən edir.
• Scope-lar: açar yaradılarkən sabit imkanlar kataloqundan seçilir. Açar heç vaxt onu yaradan üzvdən artıq iş görə bilməz: hər çağırışda hər iki şərt yoxlanılır, imkan açarın scope-larındadır və üzv hələ də ona malikdir. Üzvün rolunu daraldın, açar da onunla birlikdə daralacaq.
• Qüvvədə olma müddəti: açarların müddəti öz-özünə bitmir. Açarı profil səhifəsindən və ya DELETE /api/v1/tokens/:id ilə ləğv edin; ləğv dərhal qüvvəyə minir. Yerində rotasiya yoxdur: ləğv edin və yeni açar yaradın.
• Yaradılma və ləğv audit jurnalına yazılır.

Onu bearer token kimi göndərin - ayrıca API açarı başlığı yoxdur:

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

Plagin API açarı ilə sorğular dəqiqədə 300 ilə məhdudlaşır.

JWT sessiyaları

Veb tətbiq və mobil SDK-lar e-poçt və parolla (və ya Google və ya Apple ilə) daxil olur və token cütü alır.

Token	Qüvvədə olma müddəti	Qeydlər
Access token	15 dəqiqə	RS256, /.well-known/jwks.json ünvanındakı JWKS ilə yoxlanılır
Refresh token	30 gün	Hər yeniləmədə rotasiya olunur; rotasiya olunmuş tokenin təkrar istifadəsi bütün zənciri ləğv edir

Claim-lər: sub (istifadəçi), acc (hesab), rl (rol) və sayt üzrə rollar üçün sts (icazə verilən saytlar).

POST /auth/login, /auth/refresh, /auth/swap-company və /auth/logout növbəti bölmədə təsvir olunan X-Account-Id başlığını daşımamalı olan yeganə autentifikasiya axını endpoint-ləridir.

X-Account-Id başlığı

Yuxarıdakı dördündən başqa hər autentifikasiyalı sorğu üzərində əməliyyat apardığı hesabı daşımalıdır:

X-Account-Id: <account uuid>

Server başlığın tokenin acc claim-inə (və ya API açarının hesabına) bərabər olduğunu yoxlayır. Başlığın olmaması 400 missing_required_header, uyğunsuzluq isə 403 account_context_mismatch deməkdir. Başlıq ona görə mövcuddur ki, müştəri tərəfindəki xəta və ya təkrar istifadə olunan token heç vaxt başqa tenant-ın məlumatlarını səssizcə oxuya bilməsin: uyğunsuzluq istənilən sorğu icra olunmazdan əvvəl rədd edilir və hər log sətri tokeni deşifrə etmədən hesaba aid edilə bilir.

Çoxşirkətli istifadəçilər

Bir şəxs bir neçə şirkətə aid ola bilər. Hər şirkətin öz tokeni (öz acc claim-i) var. Keçid etmək üçün:

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

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

Hədəf çağıranın available_companies siyahısından (girişdə qaytarılır) biri olmalıdır, əks halda 403 forbidden. Cavab hədəfə aid yeni access və refresh token cütüdür; köhnə refresh token ləğv edilir və auth.account.swapped audit hadisəsi yazılır.

Çoxfaktorlu autentifikasiya

TOTP əsaslı MFA hər üzv üçün aktivləşdirilə və hər hesab üçün məcburi edilə bilər. Aktiv olduqda POST /auth/login yoxlama sorğusu qaytarır və sessiya POST /auth/mfa/verify ilə tamamlanır. Ehtiyat kodlar aktivləşdirmə zamanı verilir.

Girişin qorunması

• Giriş marşrutları IP üzrə dəqiqədə 10 cəhd və e-poçt üzrə 15 dəqiqədə 5 cəhdlə məhdudlaşır.
• On uğursuz giriş cəhdi e-poçtu 30 dəqiqəlik bloklayır; cavab code: account_locked daşıyır.
• reCAPTCHA hər əməliyyat üçün (qeydiyyat, giriş, parolun bərpası) aktivləşdirilə bilər; açıq ilkin konfiqurasiya GET /api/v1/captcha ünvanından verilir.