प्रमाणीकरण

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) से साइन इन करते हैं और टोकन की एक जोड़ी पाते हैं।

टोकन	अवधि	टिप्पणी
एक्सेस टोकन	15 मिनट	RS256, /.well-known/jwks.json पर JWKS से सत्यापित
रिफ़्रेश टोकन	30 दिन	हर रिफ़्रेश पर बदलता है; बदले जा चुके टोकन का दोबारा उपयोग पूरी चेन रद्द कर देता है

क्लेम: 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। जवाब लक्ष्य के दायरे वाली एक्सेस और रिफ़्रेश टोकन की नई जोड़ी है; पुराना रिफ़्रेश टोकन रद्द होता है और 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 से मिलता है।