REST API v1 · 開發者
驗證:API 金鑰與權限範圍
每個對 BotGG API 的請求,都會在 Authorization 標頭帶上該伺服器專屬的 API 金鑰。金鑰有權限範圍、可設定有效期限、能隨時撤銷,而且只能從後端伺服器使用,絕不能從瀏覽器使用。
開發者文件
本頁目錄
API 金鑰
金鑰是 botgg_ 加上 43 個隨機字元(256 位元)。BotGG 只儲存它的 SHA-256 雜湊值,以及像 botgg_AbCd1234 這樣的短前綴,方便你在控制台辨識,包含我們在內,沒有人能再次顯示完整的金鑰。
- 開啟控制台,選擇你的伺服器,並進入側邊欄的 API。你需要有「管理伺服器」(Manage Server)權限。
- 建立金鑰:輸入名稱(例如「網站」)、選擇需要的權限範圍,並可選擇 30、90 或 365 天的有效期限。
- 請立刻複製金鑰(只會顯示一次),並將它當作機密儲存在你的伺服器上,例如存成
BOTGG_API_KEY。
- 一把金鑰只屬於一個伺服器。拿它存取其他伺服器會回傳
403 GUILD_MISMATCH。 - 每個伺服器可啟用的金鑰數量:Free 方案 2 把,Pro 方案 10 把。
- 過期的金鑰會回傳
401 API_KEY_EXPIRED;被撤銷的金鑰則會立即回傳401 API_KEY_REVOKED。 - 建立與撤銷金鑰都會記錄在控制台的稽核日誌中。即使建立金鑰的人離開,金鑰仍然有效,因為它屬於伺服器,就像機器人的權杖一樣。
傳送金鑰
請在每個請求的 Authorization 標頭中,以 Bearer 格式傳送金鑰。不使用 Cookie,也沒有工作階段,每個請求都是獨立的。
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。
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,所以請只給每把金鑰程式實際需要的權限。參考文件中的每個端點都會標示它所需的範圍。
| 範圍 | 允許的操作 |
|---|---|
guild:read | 讀取伺服器資訊 — 伺服器名稱、圖示、成員數、語言與已啟用的功能;身分組、頻道與基本成員資訊(身分組、暱稱、加入日期)。 |
bank:read | 讀取銀行 — 餘額、成員的交易紀錄與排行榜。 |
bank:write | 變更餘額 — 為成員增加或扣除貨幣。每次變更都會寫入銀行帳本。 |
levels:read | 讀取等級 — 成員的等級、經驗值與排名,以及經驗值排行榜。 |
levels:write | 變更經驗值 — 增加、扣除或設定成員的經驗值。獎勵身分組與升級公告的運作方式與 /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 次操作。 任何持有此金鑰的人都能以你的名義處罰成員。請妥善保密,不使用時請撤銷。 |
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 連線。