Discord Bot Setup Guide

What you need first

Three things, and the order matters:

• Manage Server permission in the Discord server you are setting up, or ownership of it.
• At least one GameGrid server on your account.
• An API key created for the bot, with the scopes below. Create it before you start - /setup will not accept anything else.

Setting up takes about five minutes. The bot never asks for your GameGrid password; the API key is the only credential it holds.

Step 1 - Create the key

In the customer panel, go to Account → API Keys and create a key named for the bot - discord-bot is fine.

Do not reuse a key you already use for scripts. A dedicated key means you can rotate or revoke the bot without breaking anything else, and the audit trail shows which integration made each call.

Then choose scopes. (Limiting a key to particular servers is enforced by the platform but is not on the create form — open a ticket if you want the bot's key restricted that way.)

The scopes, by what you want to enable

Grant only the rows you want. Each block is independent - skipping one just means those commands return a scope error.

To enable every command the bot has, grant all 38 of these: servers:read, servers:write, servers:lifecycle, console:read, console:write, logs:read, files:read, settings:read, settings:write, players:read, backups:read, backups:create, backups:write, backups:restore, mods:read, mods:write, windrose:admin, account:read, billing:read, tickets:read, economy:read, economy:write, economy:admin, config_events:read, config_events:write, config_events:control, map:read, ingame:read, ingame:message, command_schedules:read, command_schedules:write, command_schedules:control, metrics:read, player_metrics:read, metrics:admin, leaderboards:write, players_self:read, players_self:write.

The Discord bot preset in the key-creation screen is a starting point, not the full set. It covers the common read and control commands but omits logs:read, files:read, settings:write, servers:write, the three write-side backup scopes, mods:write, windrose:admin, billing:read, all three economy scopes, map:read and metrics:admin. If you want the economy commands, the chat bridge, backups beyond listing, or log mirroring, add those scopes yourself.

map:read is the one the preset leaves out on purpose rather than for brevity: it reads where your players are standing, and that is a thing to hand a bot deliberately. Tick it yourself if you want the map commands. The key-creation screen says the same next to the preset, and the bot names the missing scope when a map command is refused.

The preset does include player_metrics:read, which lets /metrics top, /metrics player and /metrics sessions read your players' statistics by name. Those replies are only ever shown to the person who asked, and the abilities behind them start at the operator preset. It never reads live positions or addresses. metrics:admin (starting a new stats season) is in no preset: tick it yourself, on a key you create as the account owner or an administrator. The preset also includes leaderboards:write, so the bot can set up and post the leaderboards you switch on, and players_self:read and players_self:write for /my: each member sees only their own statistics, and only once you switch player self-service on in Player access.

Copy the key. It is shown once.

Step 2 - Invite the bot

Use the invite link on the Discord Bot page in the panel. It requests four Discord permissions and nothing more:

It does not ask to read message history, manage messages, mention everyone, kick, ban, or manage roles. Pick your Discord server and authorize. Commands appear within a minute or two.

Step 3 - Link the key

In any channel the bot can see:

/setup api-key:gsk_your_key_here

The reply is private, so your key is never posted to the channel. The bot verifies the key against the API before storing anything, then encrypts it at rest.

Who can re-run `/setup` later is narrower than who can run it first. The first /setup needs Manage Server. Re-linking a different key afterwards is limited to the Discord server owner and the person who ran `/setup` originally, while they still hold Manage Server. And a re-link with a key from a different GameGrid account clears every role grant, channel binding and live mirror (a key from the same account keeps them) - see Discord Bot Permissions & Security before you rotate.

Step 4 - Decide who can do what

Until you grant a role, nobody can run anything except the setup user and the Discord server owner. Every role starts with nothing.

The bot binds abilities to your own Discord roles - whatever you called them. Start from a preset and then adjust:

/permissions preset role:@Members preset:member
/permissions preset role:@Admins preset:moderator
/permissions grant role:@Helpers capability:server.restart
/permissions revoke role:@Helpers capability:settings.write

A preset is a starting point, not a ceiling: /permissions grant and /permissions revoke change one ability at a time, which is how you say "may restart the server, may not change its settings".

A member holding several roles gets the union of what those roles grant - a role never takes away what another gave, and Discord's role ordering makes no difference.

@everyone is held by every current and future member, so the bot refuses to give it anything destructive or account-facing, and a preset applied to it is filtered down to the safe part.

Check your work with /permissions list, /permissions role role:@YourRole, and /config view for your channels and the default server.

Step 5 - Point commands at the right server

Most server commands take an optional server-id (/buy, /kits show and /kits claim require one). When it is left out, the bot resolves the server in this order:

1. The server bound to the channel the command was run in.

2. The Discord server's default server.

3. Neither - the bot says so and names all three ways to fix it.

Run /servers to see your server ids, then set whichever fits:

/config default-server server-id:00000044
/config channel-server channel:#minecraft server-id:00000044

Channel bindings are the better answer once you run more than one server: #minecraft and #valheim each act on their own server, and nobody has to remember an id. To unbind a channel, run /config channel-server for it with no server-id.

Optional - channels the bot can use

Live mirrors and the alert channel should point at channels your admins can read and your members cannot. Credentials and IP addresses are redacted from mirrored output, but console text is still console text.

A few numbers worth knowing when you set these up. Alerts are checked every 30 seconds, and only fire on real transitions - a server going from stopped to running, or crashing. Console and log mirrors update every 10 seconds, in batches of up to 40 lines. The chat bridge polls every 5 seconds and posts up to 10 messages per cycle, telling you in the channel if a busy period meant some were skipped.

One thing to know about alerts after a restart: the bot records each server's current state without announcing it when it starts up. That stops a burst of alerts every time the bot restarts - but it also means a change that happened while the bot was offline is never announced.

Check it works

Run these in order. Each one tests something different:

If something is refused, the message tells you which gate stopped it. A message naming an ability - "You need Restart a server (server.restart)" - is a Discord role problem, fixed with /permissions grant. A message naming a scope is a key problem, and no Discord role can fix it: create a new key in the panel with that scope added and re-run /setup.

Common problems

Next: Discord Bot Commands Reference for every command, and Discord Bot Permissions & Security for how the two permission gates interact.