Omniscol API — טוקני אימות

Premium

Omniscol API: Omniscol חושפת API מסוג REST המתועד ב-OpenAPI לשילובים בין מערכות — לוח מחוונים חיצוני, תצוגה מותאמת אישית, סנכרון עם ERP או עם מערכת מידע, סוכן AI דרך MCP. טוקני גישה, המוגבלים לנקודות הקצה שנבחרו בעת יצירתם, מנוהלים מהממשק בחשבונות שמציעים שילוב זה.

Omniscol API היא API מסוג REST המתועד ב-OpenAPI. היא משמשת לשילובים בין מערכות: לוח מחוונים חיצוני, תצוגה מותאמת אישית, סנכרון עם ERP או עם מערכת מידע, או סוכן AI דרך MCP.

טוקני ה-API שניתן לנהל מהממשק קיימים בחשבונות שמציעים שילוב זה. טוקן נגזר מעניק גישה אך ורק לנקודות הקצה של ה-API שנבחרו בעת יצירתו; אין להניח שהוא מכסה את כל ה-API.

מפתח וטוקן: שני אובייקטים נפרדים

Omniscol מבחינה בין שני אובייקטים שאין לבלבל ביניהם.

מפתח הוא אובייקט קבוע, השמור בצד של Omniscol. הוא כולל:

  • מזהה קצר, שנוצר באקראי וציבורי: הוא מוצג ברשימה, והוא נישא בכל טוקן כדי לציין איזה מפתח יש לאמת;
  • תווית תיאורית, שניתן לשנות בכל עת;
  • תאריך תפוגה אופציונלי, שניתן לשנות בכל עת;
  • סוד אקראי ארוך, שנוצר בצד השרת ומשמש מפתח חתימה קריפטוגרפי.

המזהה, התווית ותאריך התפוגה הם נתוני ניהול: המזהה הוא רק הפניה ציבורית, לא רכיב סודי. הסוד, לעומת זאת, הוא חומר החתימה היחיד: הוא נוצר באקראי עם יצירת המפתח, נשאר בצד השרת, אינו ניתן לשינוי, ואינו מוצג ואינו מוחזר לעולם — לא בעת היצירה ולא ברשימת המפתחות. וגם אם הוא ידלוף, הוא לא יספיק כדי לזייף טוקן: החתימה משלבת אותו עם מלח ייחודי לחשבון ועם סוד שרת שגם הם אינם יוצאים לעולם מ-Omniscol.

טוקן הוא JWT (JSON Web Token) עצמאי, החתום בסוד של המפתח. זהו הטוקן שאתם מוסרים למערכת החיצונית. התוכן החתום שלו נושא את החשבון הנוגע בדבר, את רשימת נקודות הקצה המורשות, את המפתח שממנו הוא נגזר ואת תאריך התפוגה שלו עצמו.

במילים אחרות: מפתח חותם, טוקן חתום. מפתח אחד יכול לחתום על כמה טוקנים — כולם ניתנים לאימות באותו סוד, ולכן כולם מבוטלים יחד אם המפתח נעלם.

Omniscol אינה שומרת את הטוקן: היא יוצרת אותו, מציגה אותו פעם אחת, ואז מאמתת אותו מחדש בכל קריאה על ידי שחזור החתימה מתוך הסוד של המפתח (HMAC SHA-256). לכן אי אפשר לשנות שום הרשאה שהטוקן נושא בלי הסוד הזה.

יצירת טוקן

המסך שיתוף נמצא במודול ניהול → ייבוא / ייצוא בחשבונות Premium. היצירה נעשית בשני שלבים: תחילה יוצרים מפתח, ואז מפיקים טוקן מאותו מפתח.

  1. יצירת מפתח — הזינו תווית ברורה, ואם הגישה זמנית, גם תאריך תפוגה. התווית והתפוגה ניתנות לשינוי גם אחר כך; סוד החתימה אינו ניתן לשינוי.
  2. הפקת טוקן — בחרו את המפתח, סמנו את נקודות הקצה המורשות, אם תרצו, בחרו תאריך תפוגה ייחודי לטוקן, ואז הפיקו את ה-JWT.

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

יש אפוא שתי רמות תפוגה, בלתי תלויות זו בזו:

  • תפוגת המפתח — ניתנת לשינוי מרשימת המפתחות; משהגיעה, כל הטוקנים הנגזרים מהמפתח נדחים (הקריאה נכשלת עם שגיאה 401);
  • תפוגת הטוקן — נקבעת בעת ההפקה, כתובה ב-JWT, ואינה ניתנת לשינוי לאחר מכן.

נקודות קצה מורשות

טוקן מעניק גישה אך ורק לנקודות הקצה שסומנו בעת הפקתו: אין להניח לעולם שהוא מכסה את כל ה-API. הרשימה המורשית נישאת בטוקן ונבדקת בכל קריאה; קריאה לנקודת קצה שאינה מורשית נדחית (401).

מעבר לנקודות הקצה הבודדות, רשימת הבחירה מציעה קיצורי דרך לפי מודול:

  • הערך של מודול בלבד מתיר את כל נקודות הקצה שלו;
  • הגרסאות לפי פעולה — קריאה, שינוי, יצירה, מחיקה — מגבילות את המודול לסוג קריאה אחד.

כך סימון "מערכת שעות [קריאה]" מעניק קריאה מלאה של מערכות השעות בלי לפתוח שום כתיבה, ובלי לסמן כל נקודת קצה בנפרד. הקפידו על מינימום: הענקו רק את המודולים והפעולות הנחוצים בהחלט לשילוב.

שימוש בטוקן

שתי דרכים מקובלות לשלוח את הטוקן ל-API:

  • כותרת HTTP: Authorization: Bearer <טוקן> (מומלץ).
  • Query string: ?auth=<טוקן> (נוח לניפוי שגיאות, אך מופיע ביומני HTTP — יש להימנע ממנו בייצור).

דוגמת curl, להתאמה עם נקודת קצה אמיתית מתוך ה-OpenAPI:

curl -H "Authorization: Bearer $TOKEN" \
  https://votre-ecole.omniscol.com/api/<module>/<point-acces>

תיעוד OpenAPI

מסך ייבוא / ייצוא מציג קישור OpenAPI 3.1 שפותח ב-Swagger Editor את המפרט של החשבון. תמצאו שם:

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

המפרט מוגש גם ישירות מהחשבון שלכם, ללא אימות:

  • /api/guest/openapi.json — המפרט בפורמט JSON;
  • /api/guest/openapi.yaml (או /api/guest/openapi?yaml=true) — אותו תוכן בפורמט YAML;
  • /api/guest/school_schema.json — סכמת JSON של נתוני החשבון.

ביטול גישה

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

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

עבור מחלקת טכנולוגיות המידע, שתי השלכות:

  • אין ביטול טוקן אחר טוקן. Omniscol אינה שומרת את ה-JWT שהונפקו ואינה יכולה לבטל אחד מהם בנפרד: טוקן שכבר הופק נשאר תקף עד התפוגה שלו, או עד שהמפתח שלו נמחק או פג תוקפו.
  • שינוי תפוגת מפתח משפיע מיד על כל הטוקנים שלו: הקדמת התאריך חוסמת את הגישה של כל הטוקנים שהופקו מהמפתח.

נוהג מומלץ: מחקו מיד כל מפתח שאתם חושדים שדלף, ואז צרו מפתח חלופי עם תווית ברורה.

מפתח אחד לכל יעד ולכל שימוש

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

לעומת זאת, מפתח יחיד המשותף לכמה מערכות הופך כל ביטול לפגיעה רחבה: מחיקת המפתח שנפגע חותכת בבת אחת את כל המערכות שהשתמשו בו.

לאילו שילובים

ה-API משמש בדרך כלל עבור:

  • מערכות שילוט מותאמות אישית (מעבר ללוחות התצוגה המקוריים של Omniscol; ראו התאמת לוחות תצוגה),
  • לוחות מחוונים חיצוניים המאחדים את Omniscol עם מקורות אחרים,
  • מחברים או סנכרונים עם ERP או עם מערכת מידע עסקית,
  • סוכני AI התומכים ב-MCP הצורכים את Omniscol דרך שרת ה-MCP; ראו MCP — חיבור סוכן AI חיצוני.

לגישה מואצלת לשירות צד שלישי מזוהה (טוקן מוגבל היקף, הסכמת המשתמש, ניתן לביטול על ידי השבתת הלקוח), העדיפו את שרת OAuth2 של Omniscol: ראו OAuth2 / OIDC (ספק).

מדריך

הפקת טוקן API

  1. טוקן אימות מאפשר למערכת חיצונית (לוח מחוונים, שילוט, סוכן AI דרך MCP) לפנות אל נקודות הקצה של ה-API שבחרתם.

  2. עברו למודול ניהול → ייבוא / ייצוא, ואז פתחו את מסך השיתוף באמצעות הכפתור שיתוף. שם תראו את המפתחות הקיימים, את התוויות שלהם ואת תאריכי התפוגה שלהם, אם יש.

  3. צרו מפתח אם יש צורך. הזינו תווית ברורה (לוח מחוונים כספים, שילוט בלובי הראשי, סוכן AI Claude desktop) ותפוגה אם השילוב זמני. תוכלו לשנות את תפוגת המפתח מאוחר יותר.

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

  5. הפיקו את הטוקן, ואז העתיקו מיד את ה-JWT המוצג. הוא לא יוצג שוב ואת התפוגה שלו לא ניתן יהיה לשנות. השתמשו בו לאחר מכן בכותרת HTTP Authorization: Bearer <טוקן>.

  6. כדי לבטל את הגישה, מחקו את המפתח המתאים. הטוקנים שהופקו ממנו הופכים לבלתי תקפים.

ראו גם