התחברות

אימות

אימות API, מחזור החיים של סשן ושיטות עבודה מומלצות לאבטחה

Cliqer מבצעת אימות באמצעות עוגיית סשן מסוג httpOnly (session_token), שנוצרת על ידי POST /api/auth/login. דפדפנים שולחים אותה אוטומטית בכל בקשה; כלים לתקשורת בין שרתים שומרים אותה במאגר עוגיות (cookie jar). צוותי Studio 8K ו-Enterprise יכולים בנוסף ליצור מפתחות API לגישה בין שרתים, שנשלחים בתור Authorization: Bearer cliqer_<key>, ראו אימות באמצעות מפתח API בהמשך.

מודל הסשן

פרט הזדהותהיכן הוא נשמראיך מקבלים אותו
עוגיית סשן (session_token)עוגייה מסוג httpOnly ו-Secure במארח Cliqer שלכםנקבעת על ידי POST /api/auth/login, ומוחלפת אוטומטית על ידי השרת

העוגייה היא HttpOnly, ולכן לא ניתן לקרוא אותה מ-JavaScript. משך החיים שלה תואם ל-TTL של הסשן בשרת, והיא מתחדשת באופן שקוף בכל פעם שקוראים ל-GET /api/auth/me. אין נקודת קצה נפרדת לרענון שצריך לקרוא לה; כדי לשמור על לקוח שפועל לאורך זמן במצב תקין, יש לקרוא ל-GET /api/auth/me מעת לעת.

מחזור החיים של הסשן

שימוש בסשן

דפדפנים מצרפים את העוגייה אוטומטית. בלקוחות שפועלים בין שרתים, יש לשמור את העוגייה שתגובת ההתחברות קובעת ולשלוח אותה בבקשות הבאות:

# Save the session cookie on login, then reuse it
curl -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","password":"your_password"}'

curl -X GET "$BASE_URL/api/auth/me" -b cookies.txt

אימות באמצעות מפתח API

צוותי Studio 8K ו-Enterprise יכולים ליצור מפתחות API ארוכי טווח לגישה בין שרתים, כחלופה להחזקת פרטי ההתחברות של משתמש. אפשר ליצור ולבטל אותם בלוח הבקרה תחת צוות → מפתחות API (/dash/team/api-keys); יצירת מפתח שמורה לבעלי הצוות (או לתפקיד מותאם אישית שקיבל את ההרשאה למפתחות API). ניהול מפתחות זמין בתוכניות Studio 8K ו-Enterprise בלבד.

דף מפתחות ה-API בלוח הבקרה, תחת צוות בסרגל הצד, עם הכפתור ליצירת מפתח והערה על שליחת מפתח כאסימון Bearer

המפתח מוצג פעם אחת בלבד, בעת היצירה, בתבנית cliqer_<prefix>_<secret>. יש לשמור אותו במקום מאובטח: לא ניתן לשחזר אותו, ולכן אם הוא אובד יש לבטל אותו וליצור מפתח חדש. שלחו אותו כאסימון Bearer לכל נקודת קצה של REST שמקבלת סשן:

curl -X GET "$BASE_URL/api/licenses/status?license_key=YOUR_LICENSE_KEY" \
  -H "Authorization: Bearer cliqer_ab12cd34_your_secret_here"

מפתחות API פועלים בנקודות הקצה של REST בלבד. ה-WebSocket, כולל השליטה בשקפים, דורש אסימון סשן.

המפתח מאמת בתור המשתמש שיצר אותו, בהיקף הצוות והתוכנית של אותו משתמש. מפתח שבוטל או שאינו מוכר מחזיר 401, בדיוק כמו סשן חסר. נקודות קצה המיועדות למנהלים בלבד דוחות תמיד מפתחות API עם 403. על מפתחות חלות אותן מגבלות קצב כמו על בקשות סשן.

יש להתייחס למפתח API כמו לסיסמה. כל מי שמחזיק בו יכול לפעול בשם החשבון שלכם בנקודות הקצה המתועדות, עד שתבטלו אותו.

התחברות

החלפת פרטי ההתחברות של המשתמש בסשן. במקרה של הצלחה, התגובה קובעת את העוגייה session_token.

נקודת קצה: POST /api/auth/login

פרמטרסוגחובהתיאור
emailstringכןכתובת האימייל של המשתמש (גם שם משתמש של WordPress מתקבל)
passwordstringכןסיסמת המשתמש
otpstringלאקוד TOTP, כשהחשבון משתמש באפליקציית אימות
email_otpstringלאקוד PIN שנשלח באימייל, כשהחשבון משתמש באימות דו-שלבי באימייל
curl -X POST "$BASE_URL/api/auth/login" \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"email":"user@example.com","password":"your_password"}'

תגובה (הצלחה): קובעת את העוגייה session_token ומחזירה את המטא-דאטה של הסשן.

{
  "data": {
    "expires": 604800000
  }
}

תגובה (נדרש אימות דו-שלבי): אות 200 לבקרת זרימה, לא שגיאה. יש לשלוח שוב POST /api/auth/login עם אותם פרטי התחברות, בתוספת otp (אפליקציית אימות) או email_otp (קוד PIN שנשלח באימייל).

{
  "requires_otp": true,
  "method": "totp",
  "email_sent": false
}

method הוא אחד מהערכים totp, email או both. עבור email, השרת שולח קוד PIN באימייל, ו-email_sent מציין אם האימייל נשלח בפועל. חשבון מסוג both מתחבר באמצעות קוד אפליקציית האימות (otp); קוד ה-PIN שנשלח באימייל אינו גורם התחברות עבורו.

פרטי התחברות שגויים מחזירים 401, וכך גם קוד TOTP שגוי או שתוקפו פג. גם קוד PIN שנשלח באימייל שגוי או שתוקפו פג מחזיר 401, עם אותה הודעה כמו סיסמה שגויה. חברים בארגון שמחייב כניסה יחידה (SSO) מקבלים 403 וחייבים להתחבר באמצעות SSO (ראו שאלות נפוצות על SSO).

החלפת סשן

אין נקודת קצה נפרדת לרענון. השרת מחליף עבורכם את העוגייה session_token: כשסשן קרוב מספיק לתפוגה, GET /api/auth/me מגיב עם Set-Cookie חדש לצד הפרופיל. לקוח ששומר מאגר עוגיות וקורא ל-GET /api/auth/me מעת לעת נשאר מחובר ללא הגבלת זמן, בלי שום עבודה נוספת.


המשתמש הנוכחי

החזרת הפרופיל של המשתמש המאומת, או { "data": null } כשאין סשן תקף (מתאים גם לגישה אנונימית, אף פעם לא 401).

נקודת קצה: GET /api/auth/me

curl -X GET "$BASE_URL/api/auth/me" -b cookies.txt

תגובה:

{
  "data": {
    "id": "uuid",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "role": "uuid",
    "tfa_method": "none",
    "is_admin": false
  }
}

התנתקות

סיום הסשן של העוגייה הנוכחית ומחיקתה מהדפדפן.

נקודת קצה: POST /api/auth/logout

curl -X POST "$BASE_URL/api/auth/logout" -b cookies.txt -c cookies.txt

תגובה:

{
  "success": true
}

שיטות עבודה מומלצות לאבטחה

אמצעי אבטחה מומלצים
  1. להשתמש ב-HTTPS בלבד: עוגיית הסשן היא Secure; כל הבקשות חייבות להשתמש ב-TLS 1.2 ומעלה.
  2. לעולם לא לקרוא את העוגייה מ-JavaScript: היא HttpOnly מתוך תכנון, וכך היא צריכה להישאר.
  3. לרענן באופן יזום: בכרטיסיות שנשארות פתוחות לאורך זמן, יש לקרוא ל-GET /api/auth/me לפני שתוקף הסשן פג; השרת מחליף את העוגייה עבורכם.
  4. להתנתק כדי לבטל: POST /api/auth/logout מסיים את הסשן בצד השרת באופן מיידי.
  5. לשמור פרטי התחברות, לא סשנים: אינטגרציות בין שרתים צריכות להחזיק את פרטי ההתחברות במנהל סודות וליצור סשן מחדש, ולעולם לא לשמור את העוגייה בקוד המקור.
ראו סקירת אבטחה לפרטים על תכונות האבטחה לארגונים.