REST API v1 · 開發者

驗證:API 金鑰與權限範圍

每個對 BotGG API 的請求,都會在 Authorization 標頭帶上該伺服器專屬的 API 金鑰。金鑰有權限範圍、可設定有效期限、能隨時撤銷,而且只能從後端伺服器使用,絕不能從瀏覽器使用。

開發者文件
本頁目錄

API 金鑰

金鑰是 botgg_ 加上 43 個隨機字元(256 位元)。BotGG 只儲存它的 SHA-256 雜湊值,以及像 botgg_AbCd1234 這樣的短前綴,方便你在控制台辨識,包含我們在內,沒有人能再次顯示完整的金鑰。

  1. 開啟控制台,選擇你的伺服器,並進入側邊欄的 API。你需要有「管理伺服器」(Manage Server)權限。
  2. 建立金鑰:輸入名稱(例如「網站」)、選擇需要的權限範圍,並可選擇 30、90 或 365 天的有效期限。
  3. 請立刻複製金鑰(只會顯示一次),並將它當作機密儲存在你的伺服器上,例如存成 BOTGG_API_KEY。
  • 一把金鑰只屬於一個伺服器。拿它存取其他伺服器會回傳 403 GUILD_MISMATCH。
  • 每個伺服器可啟用的金鑰數量:Free 方案 2 把,Pro 方案 10 把。
  • 過期的金鑰會回傳 401 API_KEY_EXPIRED;被撤銷的金鑰則會立即回傳 401 API_KEY_REVOKED。
  • 建立與撤銷金鑰都會記錄在控制台的稽核日誌中。即使建立金鑰的人離開,金鑰仍然有效,因為它屬於伺服器,就像機器人的權杖一樣。

傳送金鑰

請在每個請求的 Authorization 標頭中,以 Bearer 格式傳送金鑰。不使用 Cookie,也沒有工作階段,每個請求都是獨立的。

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讀取等級 — 成員的等級、經驗值與排名,以及經驗值排行榜。
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 次操作。
任何持有此金鑰的人都能以你的名義處罰成員。請妥善保密,不使用時請撤銷。
回應 · 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 連線。

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。