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

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

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

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

X-Syncanix-Intent: base64url(JSON({ "payload": <obj>, "signature": "<hex>" }))
payload   = { v: 2, toolCallId, tenantId, sub, aud, operation, argsHash, nonce, issuedAt, expiresAt, requiresStepUp? }
signature = hex(HMAC-SHA256(JSON(payload), secret))

// v1 (legacy) payloads — { toolCallId, tenantId, userId?, method, path, issuedAt,
// expiresAt } with no "v" field — remain accepted during the dual-accept window.

מעטפת v2 היא מה שהופך קריאה שמקורה בצ'אט לבטוחה לביצוע: sub הוא זהות הביקורת שהפעולה רצה בשמה, aud קושר את האסימון ל-API שלכם כך שלא ניתן לשחזר אותו מול טננט אחר, argsHash מקבע את הארגומנטים המדויקים כך שלא ניתן לשבש את הגוף לאחר החתימה, וה-nonce החד-פעמי מונע שחזור של האסימון כולו בתוך חלון התוקף שלו.

toolCallId

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

tenantId

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

sub

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

aud

קהל ה-API של הלקוח שאליו הכוונה קשורה — כך שהפרדת הטננטים אינה נשענת עוד על סוד ה-HMAC לבדו. דחו אסימון שה-aud שלו אינו שלכם.

operation

הפעולה שהכוונה הזו מאשרת, במונחי שכבת התעבורה (למשל מתודת HTTP ונתיב). האימות נכשל אם אינה תואמת את הבקשה בפועל.

argsHash

SHA-256 בהקסדצימלי באותיות קטנות של ארגומנטי הקריאה לאחר קנוניזציה. חשבו אותו מחדש מגוף הבקשה ודחו בעת אי-התאמה — זה סוגר שחזור המבוסס על שיבוש הגוף.

nonce

ערך לשימוש חד-פעמי שהמאמת שלכם רושם ומסרב לקבל פעמיים, וכך נסגר שחזור בתוך חלון התוקף (TTL).

issuedAt, expiresAt

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

requiresStepUp (optional)

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

אסימוני v1 ישנים — ללא שדה v, הקושרים רק מתודה ונתיב עם userId אופציונלי — ממשיכים להתקבל במהלך חלון המעבר של הקבלה הכפולה, כך ששרתים שכבר שולבו ממשיכים לאמת בזמן שאתם משדרגים. אסימונים חדשים מונפקים כ-v2.

כשלי אימות מחזירים 403 עם סיבה קריאת-מכונה כגון missing-header, malformed, bad-signature, expired, method-mismatch או path-mismatch; הקישור החזק יותר של act-as-user מוסיף בדיקות פעולה, ארגומנטים, קהל ושחזור. אותן מחרוזות סיבה משמשות בכל ה-SDKs.

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

כשהעוזר פועל עבור משתמש מחובר, ה-מדריך הפעולה בשם משתמש מכסה את הזרימה מקצה לקצה. ברמת החוזה, הבק-אנד שלכם מבחין בדיוק בשני דברים: מטען הכוונה נוקב בשם המשתמש הפועל (sub במעטפת ה-act-as-user המאומתת; userId במעטפת אנונימית ישנה), ופעולות כתיבה מגיעות רק לאחר ש-Syncanix הפעילה את שער האישור.

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

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

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

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