REST API v1 · Developers
Authentication: API keys and scopes
Every request to the BotGG API carries a per-server API key in the Authorization header. Keys are scoped, can expire, can be revoked at any time and only work from servers — never from browsers.
Developer docs
On this page
API keys
A key is botgg_ followed by 43 random characters (256 bits). BotGG stores only a SHA-256 hash of it plus a short prefix such as botgg_AbCd1234 so you can recognise it in the console — nobody, including us, can show you the full key again.
- Open the console, pick your server and go to API in the sidebar. You need the Manage Server permission.
- Create a key: a name (for example “Website”), the scopes it needs and an optional expiry of 30, 90 or 365 days.
- Copy the key right away — it is shown only once — and store it as a secret on your server, for example in
BOTGG_API_KEY.
- A key belongs to one server. Using it for another server answers
403 GUILD_MISMATCH. - Active keys per server: 2 on Free, 10 on Pro.
- An expired key answers
401 API_KEY_EXPIRED; a revoked key answers401 API_KEY_REVOKEDimmediately. - Creating and revoking keys is recorded in the console audit log. A key keeps working if the person who created it leaves — it belongs to the server, like a bot token.
Sending the key
Send the key in the Authorization header of every request with the Bearer scheme. There are no cookies and no sessions — every request stands on its own.
curl -s https://console.botgg.app/api/v1/guilds/123456789012345678 \
-H "Authorization: Bearer $BOTGG_API_KEY"A missing or malformed header answers 401 UNAUTHORIZED, an unknown key 401 INVALID_API_KEY. Repeated failures from one IP address are throttled with 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
A key can only call endpoints whose scope it has. Scopes are independent — bank:write does not include bank:read — so give each key exactly what its code needs. Every endpoint in the reference shows its scope.
| Scope | What it allows |
|---|---|
guild:read | Read server info — Server name, icon, member count, language and enabled features; roles, channels and basic member info (roles, nickname, join date). |
bank:read | Read Bank — Balances, a member’s transaction history and the leaderboard. |
bank:write | Change balances — Add currency to or remove it from members. Every change is written to the Bank ledger. |
levels:read | Read Levels — A member’s level, XP and rank, and the XP leaderboard. |
levels:write | Change XP — Add, remove or set members’ XP. Reward roles and level-up announcements work as with /levels commands; every change is in the audit log. |
invites:read | Read invites — A member’s invite counts and rank, and the invites leaderboard. |
invites:write | Change bonus invites — Add or remove bonus invites, like /invites add. Milestone rewards follow; every change is in the audit log. |
shop:read | Read Shop — Stores, items, members’ inventories and the purchase history. |
shop:write Sensitive | Manage Shop — Buy items for members (charged from their Bank balance, roles are given), grant items for free, refund purchases, restock and turn items on or off. |
giveaways:read | Read giveaways — Running and ended giveaways with entry counts, winners and the list of entrants. |
giveaways:write | Manage giveaways — Start giveaways, end them early and reroll winners. The bot posts and updates them in Discord. |
flows:read | Read Flows — The list of flows (name, on/off, trigger) and the status and result of runs. |
flows:run Sensitive | Run Flows — Run enabled flows that start with a Manual or Webhook trigger, with your own input. The flow does whatever its steps do; runs count toward the plan’s daily limit. |
tickets:read | Read tickets — The ticket list and details (opener, panel, status, form answers) and the saved transcripts of closed tickets. |
tickets:write | Close tickets — Close open tickets with a reason — the bot saves the transcript, logs it and notifies the opener like a staff close. |
applications:read | Read applications — Application forms and submissions, including the applicants’ answers, votes and decisions. |
applications:write | Decide applications — Accept or deny open applications. The bot gives / removes the form’s roles, DMs the applicant and updates the review like a staff decision. |
appeals:read | Read ban appeals — Ban appeals with their answers, the ban reason and the conversation (internal staff notes are never included). |
appeals:write Sensitive | Decide ban appeals — Approve (unban) or reject open ban appeals with a reason; the bot unbans and DMs like a staff decision. Approving an appeal unbans the member. |
moderation:read Sensitive | Read moderation cases — Moderation cases (warnings, timeouts, kicks, bans…) with reasons, evidence links and moderators, and the status of API actions. Exposes members’ moderation history. |
moderation:write Sensitive | Moderate members — Warn, time out, kick, ban and unban members as the key’s creator: only while they still have the matching Discord permission, only members below their and the bot’s highest role, with a reason, at most 10 actions a minute. Anyone holding this key can punish members in your name. Keep it secret and revoke it when unused. |
HTTP/1.1 403 Forbidden
{ "error": "INSUFFICIENT_SCOPE", "message": "This API key lacks the \"bank:write\" scope", "required": "bank:write" }No browser requests
To show API data on a web page, call the API from your backend and send the result to the page.
Security best practices
- Least privilege. If you only show balances or a leaderboard, create a key with read scopes only.
- Store keys as secrets — an environment variable or a secret manager, never in code or a repository.
- Expire and rotate. Give keys an expiry; to rotate, create a new key, deploy it, then revoke the old one.
- Revoke leaks immediately. Keys start with
botgg_, so secret scanners and a simple search find them easily. - HTTPS only. The API isn’t served over plain HTTP.