אימות

מפתחות API (מומלץ לאינטגרציות)

מפתח API הוא אסימון גישה אישי שקשור לחבר בחשבון שלכם.

• צרו מפתח בהגדרות ← תוספים ← מפתחות RolChat API. הסוד מוצג פעם אחת; לאחר מכן רק עשרת התווים הראשונים שלו גלויים, ו-RolChat שומר רק גיבוב SHA-256.
• פורמט: rcp_ ואחריו 32 בתים אקראיים ב-base64url, בערך 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, מאומת מול ה-JWKS בכתובת /.well-known/jwks.json
אסימון רענון	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. התגובה היא זוג חדש של אסימוני גישה ורענון בהיקף היעד; אסימון הרענון הישן מבוטל ונכתב אירוע ביקורת auth.account.swapped.

אימות רב-גורמי

אפשר לרשום MFA מבוסס TOTP לכל חבר ולחייב אותו לכל חשבון. כשהוא מופעל, POST /auth/login מחזיר אתגר והסשן מושלם עם POST /auth/mfa/verify. קודי גיבוי מונפקים בעת הרישום.

הגנה על התחברות

• נתיבי התחברות מוגבלים ל-10 ניסיונות לכל IP בדקה ול-5 לכל אימייל ב-15 דקות.
• עשר התחברויות שנכשלו נועלות את האימייל ל-30 דקות; התגובה נושאת code: account_locked.
• אפשר להפעיל reCAPTCHA לכל פעולה (הרשמה, התחברות, איפוס סיסמה); תצורת האתחול הציבורית מוגשת מ-GET /api/v1/captcha.