אימות ב-API: מפתחות והרשאות

מפתחות API

מפתח הוא botgg_ ואחריו 43 תווים אקראיים (256 ביט). BotGG שומר רק גיבוב SHA-256 שלו וקידומת קצרה כמו botgg_AbCd1234 כדי שתזהו אותו בקונסולה — אף אחד, כולל אותנו, לא יכול להציג לכם שוב את המפתח המלא.

פתחו את הקונסולה, בחרו שרת ועברו ל-API בתפריט הצד. נדרשת הרשאת Manage Server.
צרו מפתח: שם (למשל „אתר”), ההרשאות שהוא צריך ותוקף אופציונלי של 30, 90 או 365 ימים.
העתיקו את המפתח מיד — הוא מוצג פעם אחת בלבד — ושמרו אותו כסוד בשרת שלכם, למשל ב-BOTGG_API_KEY.

מפתח שייך לשרת אחד. שימוש בו עבור שרת אחר מחזיר 403 GUILD_MISMATCH.
מפתחות פעילים לשרת: 2 ב-Free, 10 ב-Pro.
מפתח שפג תוקפו מחזיר 401 API_KEY_EXPIRED; מפתח שבוטל מחזיר מיד 401 API_KEY_REVOKED.
יצירה וביטול של מפתחות נרשמים ביומן הביקורת של הקונסולה. מפתח ממשיך לעבוד גם אם מי שיצר אותו עזב — הוא שייך לשרת, כמו טוקן של בוט.

שליחת המפתח

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

curl

curl -s https://console.botgg.app/api/v1/guilds/123456789012345678 \
  -H "Authorization: Bearer $BOTGG_API_KEY"

כותרת חסרה או בפורמט שגוי מחזירה 401 UNAUTHORIZED, ומפתח לא מוכר — 401 INVALID_API_KEY. כשלונות חוזרים מאותה כתובת IP מוגבלים עם 429 RATE_LIMITED.

תשובה · 401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="BotGG API"

{ "error": "API_KEY_REVOKED", "message": "This API key was revoked" }

הרשאות (scopes)

מפתח יכול לקרוא רק לנקודות קצה שיש לו את ההרשאה שלהן. ההרשאות עצמאיות — bank:write לא כולל את bank:read — לכן תנו לכל מפתח בדיוק את מה שהקוד שלו צריך. לכל נקודת קצה במדריך העיון מצוינת ההרשאה שלה.

הרשאות של מפתחות API
הרשאה	מה היא מאפשרת
`guild:read`	קריאת פרטי השרת — שם השרת, סמל, מספר חברים, שפה ותכונות מופעלות; תפקידים, ערוצים ופרטי חבר בסיסיים (תפקידים, כינוי, תאריך הצטרפות).
`bank:read`	קריאת הבנק — יתרות, היסטוריית התנועות של חבר והטבלה המובילה.
`bank:write`	שינוי יתרות — הוספה והורדה של מטבע לחברים. כל שינוי נרשם ביומן הבנק.
`levels:read`	קריאת הרמות — הרמה, ה-XP והדירוג של חבר, וטבלת המובילים לפי XP.
`levels:write`	שינוי XP — הוספה, הורדה וקביעה של XP לחברים. תפקידי פרס והכרזות עליית רמה פועלים כמו בפקודות /levels; כל שינוי נרשם ביומן הפעולות.
`invites:read`	קריאת הזמנות — מוני ההזמנות והדירוג של חבר, וטבלת המובילים בהזמנות.
`invites:write`	שינוי הזמנות בונוס — הוספה והורדה של הזמנות בונוס, כמו /invites add. פרסי אבני דרך מוענקים בהתאם; כל שינוי נרשם ביומן הפעולות.
`shop:read`	קריאת החנות — חנויות, פריטים, המלאי של חברים והיסטוריית הרכישות.
`shop:write` רגישה	ניהול החנות — קנייה של פריטים עבור חברים (מחויב מיתרת הבנק שלהם, תפקידים מוענקים), הענקת פריטים בחינם, החזר רכישות, חידוש מלאי והפעלה או כיבוי של פריטים.
`giveaways:read`	קריאת הגרלות — הגרלות פעילות ושהסתיימו, עם מספר המשתתפים, הזוכים ורשימת המשתתפים.
`giveaways:write`	ניהול הגרלות — פתיחת הגרלות, סיום מוקדם שלהן והגרלת זוכים מחדש. הבוט מפרסם ומעדכן אותן ב-Discord.
`flows:read`	קריאת תהליכים — רשימת התהליכים (שם, פעיל/כבוי, טריגר) והסטטוס והתוצאה של הרצות.
`flows:run` רגישה	הרצת תהליכים — הרצת תהליכים פעילים שמתחילים בטריגר ידני או Webhook, עם קלט משלך. התהליך מבצע את כל השלבים שלו; ההרצות נספרות במגבלה היומית של התוכנית.
`tickets:read`	קריאת כרטיסים — רשימת הכרטיסים ופרטיהם (פותח, פאנל, סטטוס, תשובות הטופס) ותמלילים שמורים של כרטיסים סגורים.
`tickets:write`	סגירת כרטיסים — סגירת כרטיסים פתוחים עם סיבה — הבוט שומר תמליל, רושם ביומן ומודיע לפותח כמו בסגירה על ידי הצוות.
`applications:read`	קריאת מועמדויות — טפסי מועמדות והגשות, כולל תשובות המועמדים, הצבעות והחלטות.
`applications:write`	החלטה על מועמדויות — אישור או דחייה של מועמדויות פתוחות. הבוט נותן / מסיר את תפקידי הטופס, שולח הודעה למועמד ומעדכן את הדיון כמו בהחלטת צוות.
`appeals:read`	קריאת ערעורים — ערעורי הרחקה עם התשובות, סיבת ההרחקה והשיחה (הערות פנימיות של הצוות לעולם לא נכללות).
`appeals:write` רגישה	החלטה על ערעורים — אישור (ביטול הרחקה) או דחייה של ערעורים פתוחים עם סיבה; הבוט מבטל את ההרחקה ושולח הודעה כמו בהחלטת צוות. אישור ערעור מבטל את ההרחקה של החבר.
`moderation:read` רגישה	קריאת תיקי ניהול — תיקי ניהול (אזהרות, השתקות, הרחקות, חסימות…) עם סיבות, קישורי ראיות ומנהלים, וסטטוס פעולות API. חושף את היסטוריית הניהול של החברים.
`moderation:write` רגישה	ניהול חברים — אזהרה, השתקה, הרחקה, חסימה וביטול חסימה בשם יוצר המפתח: רק כל עוד יש לו את הרשאת Discord המתאימה, רק לחברים מתחת לתפקיד הגבוה שלו ושל הבוט, עם סיבה, עד 10 פעולות בדקה. כל מי שמחזיק במפתח הזה יכול להעניש חברים בשמך. שמרו אותו בסוד ובטלו אותו כשאינו בשימוש.

תשובה · 403

HTTP/1.1 403 Forbidden

{ "error": "INSUFFICIENT_SCOPE", "message": "This API key lacks the \"bank:write\" scope", "required": "bank:write" }

בלי בקשות מדפדפן

כדי להציג נתוני API בדף אינטרנט, קראו ל-API מהבקאנד שלכם והעבירו את התוצאה לדף.

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

מינימום הרשאות. אם אתם רק מציגים יתרות או טבלת מובילים, צרו מפתח עם הרשאות קריאה בלבד.
שמרו מפתחות כסודות — במשתנה סביבה או במנהל סודות, לא בקוד ולא במאגר.
תוקף והחלפה. הגדירו תוקף למפתחות; כדי להחליף מפתח, צרו חדש, פרסו אותו ורק אז בטלו את הישן.
דלף? בטלו מיד. מפתחות מתחילים ב-botgg_, כך שסורקי סודות וחיפוש פשוט מוצאים אותם בקלות.
HTTPS בלבד. ה-API לא זמין ב-HTTP רגיל.

אימות: מפתחות API והרשאות