מפתחות API, הרשאות ויומן פעולות: איך נותנים לסוכן גישה לְשַׁגֵּר בלי לאבד שליטה

לכל מפתח API בְּשַׁגֵּר יש אחת או יותר משלוש הרשאות: read לקריאה, write ליצירת טיוטות, מדיה וקבוצות, וpublish לתזמון ופרסום. הכלל הוא לתת לכל סוכן את המינימום שהוא צריך, מפתח נפרד לכל תפקיד, ולבדוק את יומן הפעולות בדף ניהול הסוכנים, שבו מתועדת כל קריאה של סוכן. רק אדם יוצר ומבטל מפתחות.

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

מה כל הרשאה מאפשרת?

הטבלה מבוססת על השדה x-scope שמופיע לכל פעולה במפרט OpenAPI של שַׁגֵּר. אותן פעולות זמינות ככלים בשרת MCP של שַׁגֵּר, עם אותן הרשאות.

הרשאה	פעולות
read	whoami, list_workspaces, list_channels, list_groups, list_posts, get_post, get_analytics
write	create_workspace, create_connect_link, create_group, upload_media_from_url, create_post (כטיוטה), request_approval, cancel_post
publish	schedule_post, וcreate_post עם schedule_at

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

איזה מפתח לתת לאיזה סוכן?

תפקיד	הרשאות	למה
סוכן דוחות	read	קורא נתונים ולא יוצר כלום
סוכן תוכן בתקופת הרצה	read, write	כותב טיוטות, אדם מתזמן
סוכן תוכן ותיק	read, write, publish	אחרי כמה שבועות בלי טעויות
סקריפט ייבוא מדיה	write	מעלה קבצים ולא קורא נתוני לקוחות

שימו לב שגם עם publish, פוסט בסביבת עבודה שמוגדרת עם אישור לקוח לא יתוזמן בלי האישור. schedule_post ייכשל עם סיבה ברורה. ההרשאה קובעת מה הסוכן רשאי לנסות, וההגדרות של סביבת העבודה קובעות מה יעבור. על שכבת האישור כתבתי במאמר על אישור אנושי לפוסטים של סוכנים.

ומה עם סוכן שנרשם בעצמו?

סוכן יכול לפתוח סנדבוקס בלי אדם, בקריאה לPOST /api/v1/agent/signup, לפי המתכון שבקובץ auth.md. הוא מקבל מפתח שמוצג פעם אחת וקישור תביעה. בסנדבוקס הוא יכול ליצור עד חמש סביבות עבודה, להעלות מדיה, ליצור טיוטות ולקרוא. הוא לא יכול לתזמן, לפרסם, ליצור קישורי חיבור או לשלוח בקשות אישור, וכל ניסיון כזה מחזיר sandbox_unclaimed.

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

איך שומרים את המפתח מחוץ לקוד?

מפתח של שַׁגֵּר מתחיל בshgr_live_, וְשַׁגֵּר שומר רק גיבוב שלו, כך שאי אפשר לשחזר אותו אחרי היצירה. אם הוא אבד, יוצרים חדש ומבטלים את הישן. הסיכון האמיתי הוא לא אובדן אלא דליפה: מפתח שנכנס לקובץ שנשמר במאגר קוד, או שהודבק בשיחה שנשמרת.

בכלי Claude Code, הקובץ .mcp.json תומך בהרחבת משתני סביבה בכותרות, כך שהמפתח נשאר במשתנה סביבה והקובץ עצמו בטוח לשמירה במאגר. התחביר מתועד בתיעוד של Claude Code על MCP:

{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${SHAGER_API_KEY}"
      }
    }
  }
}

ובסקריפטים, אותו עיקרון:

export SHAGER_API_KEY="shgr_live_..."   # מתוך מנהל הסודות, לא מקובץ במאגר
curl https://app.shager.ai/api/v1/me \
  -H "Authorization: Bearer $SHAGER_API_KEY"

הקריאה ל/me, שהיא whoami בגרסת MCP, מחזירה את הארגון, האם זה עדיין סנדבוקס, ואת רשימת ההרשאות של המפתח. זו הקריאה הראשונה שכל סוכן צריך לעשות בתחילת עבודה, ואני כותב את זה בהוראות הקבועות.

מה רואים ביומן הפעולות?

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

שלושה דברים שאני בודק ביומן פעם בשבוע:

1. כשלים חוזרים של forbidden. סוכן שמנסה שוב ושוב פעולה שאין לו הרשאה אליה הוא סוכן שההוראות שלו לא ברורות, או שמישהו ביקש ממנו משהו שלא תוכנן.
2. פעולות בשעות לא צפויות. סוכן דוחות שרץ בשלוש בלילה ביום שלישי, כשהוא אמור לרוץ פעם בשבוע, מצדיק בדיקה.
3. מפתחות שלא היו בשימוש זמן רב. מפתח שאף אחד לא משתמש בו הוא רק סיכון. מבטלים אותו.

אילו שגיאות הסוכן יכול לקבל?

כל שגיאה מוחזרת במבנה { "error": { "code", "message" } }. ההודעה מנוסחת כך שסוכן יכול להבין אותה ולדווח, והוראה טובה היא לדווח אותה כלשונה.

קוד	מצב HTTP	משמעות
unauthorized	401	אין מפתח, או שהמפתח לא תקף, פג או בוטל
forbidden	403	למפתח אין את ההרשאה שהפעולה דורשת
sandbox_unclaimed	403	סנדבוקס שעוד לא נתבע מנסה לפרסם או לחבר
rate_limited	429	מעל 120 בקשות בדקה למפתח
rejected	422	הפוסט לא עומד בכללים של אחת הרשתות, עם הסבר
invalid_input	400	שדה חסר או בפורמט לא נכון

rejected היא השגיאה המעניינת. היא אומרת שהבדיקה של שַׁגֵּר מול כללי הרשת תפסה בעיה לפני השליחה. סוכן טוב מתקן לפי ההסבר ומנסה שוב. סוכן שמנסה שוב בלי לשנות כלום צריך הוראה מפורשת שלא לעשות את זה.

מתי לבטל מפתח?

מבטלים מיד כשמפתח הופיע בקובץ במאגר קוד, בצילום מסך, בשיחה ששותפה, או אצל עובד שעזב. מבטלים גם כשמחליפים כלי, למשל מחליפים את Claude Desktop בכלי Cursor, ואין סיבה שהמפתח הישן ימשיך לחיות. הביטול נעשה בדף ניהול הסוכנים, והוא מיידי: הקריאה הבאה עם המפתח תחזיר unauthorized.

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

שאלות נפוצות

האם שרת MCP של שַׁגֵּר תומך בהתחברות OAuth?

עדיין לא. היום החיבור הוא עם מפתח בכותרת Authorization: Bearer. התחברות עם OAuth בדרך, ועד אז כלים שתומכים רק במחברים מבוססי OAuth צריכים לחכות, או לעבוד מול ממשק REST מתוך קוד.

האם כמה סוכנים יכולים להשתמש באותו מפתח?

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

מי יכול ליצור מפתחות?

רק אדם שמחובר לְשַׁגֵּר, בדף ניהול הסוכנים. סוכן לא יכול ליצור לעצמו מפתח נוסף או להרחיב את ההרשאות של המפתח שלו. הדרך היחידה של סוכן לקבל מפתח בלי אדם היא הרשמה עצמית, שמסתיימת בסנדבוקס מוגבל.