מדריך API בזמן ריצה

שלושה חוזים מחברים את Syncanix לשרת הרץ שלכם: כותרת הכוונה החתומה שמאשרת כל קריאת כלי, שדות הפעולה-בשם-משתמש שנושאים את זהות משתמש הקצה, ונתוני ה-witness שמדווחים על צורות ה-API. העמוד הזה הוא המדריך ברמת השדות; המדריכים מכסים את הזרימות.

אימות כוונה — כותרת X-Syncanix-Intent

כל קריאת כלי ש-Syncanix שולח לשרת שלכם נושאת כוונה חתומה. ה-SDK שלכם (או הקוד שלכם) מאמת את חתימת ה-HMAC-SHA256 עם סוד הטננט, בודק את התפוגה ושהמתודה והנתיב תואמים את הבקשה בפועל — ואז חושף את ה-payload המפוענח למטפל שלכם.

X-Syncanix-Intent: base64url(JSON({ "payload": <obj>, "signature": "<hex>" }))
payload   = { toolCallId, tenantId, userId?, method, path, issuedAt, expiresAt, requiresStepUp? }
signature = hex(HMAC-SHA256(JSON(payload), secret))

toolCallId

מזהה ייחודי של קריאת הכלי — השתמשו בו כמפתח אידמפוטנטיות במסירות חוזרות.

tenantId

מרחב העבודה (טננט) שלכם ב-Syncanix שאליו שייכת הקריאה.

userId

משתמש הקצה המחובר שבשמו פועל העוזר. נעדר בקריאות בלי הקשר משתמש.

method, path

מתודת ה-HTTP והנתיב שהכוונה מאשרת. האימות נכשל אם אינם תואמים את הבקשה בפועל.

issuedAt, expiresAt

חותמות זמן Unix שתוחמות את חיי הכוונה. כוונות שפג תוקפן נדחות.

requiresStepUp

אמת כשהפעולה דורשת אימות מוגבר טרי. דחו אלא אם שער ה-step-up שלכם רץ.

כשלי אימות מחזירים 403 עם סיבה קריאת-מכונה — אחת מ: missing-header, malformed, bad-signature, expired, method-mismatch, path-mismatch. הסיבות זהות בכל ה-SDKים.

פעולה בשם משתמש — מה השרת שלכם צופה בו

כשהעוזר פועל בשם משתמש מחובר, המדריך הפעולה בשם משתמש מכסה את הזרימה מקצה לקצה. ברמת החוזה, השרת שלכם צופה בדיוק בשני דברים: שדה ה-userId שב-payload מציין את המשתמש הפועל, ופעולות כתיבה מגיעות רק אחרי ש-Syncanix הריץ את שער האישור שלו.

ההרשאה נשארת שלכם: התייחסו ל-userId כאל הזהות שמולה מרשים — בדיוק כאילו המשתמש הזה קרא לנקודת הקצה ישירות. Syncanix מאשר שהקריאה הייתה מכוונת; השרת שלכם מאשר מה המשתמש הזה רשאי לעשות.

Witness — מדווח הסכמות בזמן ריצה

ה-middleware של ה-witness צופה בתעבורת ה-API שלכם כדי לשמור על דיוק קטלוג היכולות. לכל בקשה ותגובה שנצפו הוא מסיק מתאר צורה — המבנה בלי הערכים: סקלרים מדווחים רק על הטיפוס (string, number, integer, boolean, null), מערכים על צורת האיברים, ואובייקטים על צורות המאפיינים. צורות של אותם מתודה ונתיב ממוזגות בין תצפיות.

הערכים עוברים השחרה לפני ההסקה, כך שהמסיק לעולם לא רואה מחרוזות רגישות; מבנים סותרים או ריקים קורסים ל-unknown במקום לנחש.