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.

Restrict the key to the servers this Discord community actually runs, if you have others. Then choose scopes.

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 30 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, command_schedules:read, command_schedules:write, command_schedules:control.

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 and all three economy scopes. If you want the economy commands, the chat bridge, backups beyond listing, or log mirroring, add those scopes yourself.

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. And a successful re-link clears every role grant, channel binding and live mirror - 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. Map roles to levels:

/config role role:@Moderators level:Console Access
/config role role:@Admins level:Full Access

A member gets the highest level across all their roles. @everyone can be granted Read Only at most - the bot refuses anything higher.

Check your work with /config view, which lists the linked key id, your channels, the default server and every role grant.

Step 5 - Point commands at the right server

Every command takes an optional server-id. 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:srv_abc123
/config channel-server channel:#minecraft server-id:srv_abc123

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. "You need at least Full Access" is a Discord role problem, fixed with /config role. A message naming a scope is a key problem, fixed by creating a new key in the panel with that scope added and re-running /setup.

Common problems

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