Discord Bot Permissions & Security

Two gates, and the key is the ceiling

Every command passes through two independent checks, and both must allow it.

1. Your Discord roles. Which abilities has this member been granted, through the Discord roles they hold? You set this with /permissions.

2. Your API key. Does the GameGrid API key you linked with /setup carry the scope that ability needs?

The second one is not a second thing to grant. It is a limit. Everything the bot does is signed with that one key, so a Discord role can only ever grant a subset of what your API key already allows - never a superset, and never more. If your key does not carry servers:lifecycle, then no Discord role restarts a server through this bot: not a role holding every ability there is, and not the Discord server owner.

The two failures read differently, on purpose, because they have different fixes. A refusal that names an ability - "You need Restart a server (server.restart)" - is your Discord roles, and someone with /permissions can fix it. A refusal that names a scope - "it needs the servers:lifecycle API scope, and the key linked here does not carry it" - is the key, and no Discord role can fix that at all. Mint a key with the missing scope and re-run /setup.

When an ability is blocked by both, the bot names the key. Granting the role would change nothing while the key still cannot back the request, and sending you to the role editor would cost you an afternoon.

Run /permissions key to see exactly what your key allows and which abilities it therefore blocks. Run /permissions refresh-key after minting a new one.

Your roles, your abilities

The bot binds abilities to your own Discord roles, whatever you called them. There is no fixed ladder to place them on: if your server has Verified, Minecraft Player, Veteran and WDCGamegrid Helper, you grant abilities to those, by name, from the role picker Discord already gives you. You never type a role ID.

Pick a role and give it exactly what it should have:

/permissions grant role:@Helpers capability:server.restart
/permissions grant role:@Helpers capability:console.read
/permissions revoke role:@Helpers capability:settings.write

That is the thing a single access level could not say. @Helpers can bounce a stuck server and cannot change its difficulty, because restarting and changing settings are two abilities rather than one rung.

Several roles add up. A member holding Verified and Minecraft Player and Regular can do everything any of those three grants - the union, not the highest one. A role never takes away what another role gave, and the order your roles appear in on Discord's settings page makes no difference here. That order decides display colour and who can manage whom; it does not decide what the bot lets you do.

There are deliberately no denials. To take an ability away, revoke it from the role that grants it - /permissions role role:@YourRole shows you which abilities each role carries, so you can always see why someone can do something.

Every ability

A Discord role holds a set of abilities. There are 55 abilities, and every command requires one of them. A role you have never configured holds none — every role starts with nothing, including @everyone.

Grant them one at a time with /permissions grant, or start from a preset and adjust. The In preset from column names the lowest preset that includes an ability.

Servers

Settings

Console & logs

Players & files

In-game

Metrics

Backups

Mods

Windrose Plus

Events & presets

Scheduled commands

Economy

Economy admin

Chat bridge

Account & billing

Bot administration

Destructive abilities are opt-in

Destructive abilities stop a server, overwrite data, change configuration, or move currency. None is granted by default, and none can be given to @everyone - the bot refuses outright.

These 20 are destructive:

Grant these deliberately, to a named role, and check with /permissions role role:@YourRole afterwards. /permissions list shows how many destructive abilities each role holds.

Presets, and adjusting from there

A preset is a ready-made set you can then adjust one ability at a time. It is a starting point, not a ceiling.

/permissions preset role:@Verified preset:member
/permissions preset role:@Admin preset:moderator
/permissions grant role:@Helpers capability:server.restart

A preset is stored as the literal list of abilities it contains at the moment you apply it. It does not silently widen when the bot gains a new ability later - you would grant that one yourself, or re-apply the preset. There is no wildcard ability and no *, for the same reason there is none in the API scope list: a wildcard grows every time the product does, and nobody re-reads what they agreed to.

What @everyone can hold

@everyone is a real Discord role, and every member holds it - including anyone who joins from a public invite, now or in future. The bot treats it specially:

A reasonable choice for a public community is /permissions preset role:@everyone preset:member, which lets anyone check whether the server is up and use the shop, and nothing else. Leaving @everyone with nothing is also fine - that is the default.

Who can configure the bot

Configuration is not an ability you can grant yourself into. Linking the API key and pointing the bot at channels stays with two people; handing out abilities can now be delegated, and nothing else can.

bot.permissions.manage is the one piece of this you can delegate: it lets a head admin hand out abilities without ever seeing your API key. It does not lift the ceiling. Someone holding it cannot grant themselves - or anyone else - an ability your API key cannot back, because the key is checked before any Discord role is consulted. It is also limited to what the holder has: someone who passes only through bot.permissions.manage can give a role, take from a role, apply as a preset or clear only abilities they hold themselves, and never bot.permissions.manage itself. The server owner and the person who ran /setup (with Manage Server) are not limited this way.

This split is deliberate. /setup writes the credential every other command spends, so it cannot be something an ability reaches.

It also means the person who first ran /setup matters. They administer the bot only while they still hold Manage Server: if they lose it, or leave your Discord server and come back, they are an ordinary member, and the server owner can still re-run /setup and take over.

What re-running /setup does

Re-running /setup with a new key is how you rotate the bot's credentials. Verification happens before anything is stored, so a key that fails to verify leaves the working one in place - a fumbled rotation cannot take your bot offline.

A re-link with a key from the same GameGrid account keeps your configuration. A key from a different account clears it. Every role grant, every channel-to-server binding and every live console or log mirror is deleted when the new key belongs to a different account. Your log, alert and command channels and your default server survive either way.

The bot compares the account the new key belongs to with the account of the key it replaces. Rotating a key, or making a new key with more scopes, on the account that is already linked keeps everything, and the reply says so. A key from a different account clears everything, because a different account has a different set of servers and the old grants are not assumed to still be appropriate. If the bot cannot tell which account a key belongs to, it clears too: for example on a Discord server whose link was made before the bot recorded the account, when the old key has since been revoked or has expired. The entry in your log channel says "kept (same GameGrid account)" or "cleared".

If you are not sure which case applies, plan for the clearing one:

1. Run /permissions list and screenshot it, so you have every role's abilities, and /config view for your channel bindings.

2. Run /config live-list and note any live mirrors.

3. Run /setup with the new key.

4. If the reply says they were cleared, re-apply the role grants with /permissions preset and /permissions grant, re-bind channels with /config channel-server, and restart mirrors with /config live-console or /config live-logs.

5. Revoke the old key in the panel.

How your API key is protected

The key you give /setup is verified against the API before it is stored, then encrypted at rest. It is never written to a log file, never shown in a command reply, and never displayed by /config view. Only the /setup reply names it, and then only by its 8-character key id, the part that is safe to display anywhere.

The bot cannot do anything your key cannot do. If you want the bot to be able to read the console but never restart a server, create its key without servers:lifecycle - then no Discord role, no matter how it is configured, can restart anything through the bot.

Give the bot its own key, not one you also use for scripts. When you rotate or revoke it, only the bot is affected, and the audit trail tells you which integration made a call.

A related habit: check GET /account/audit if you ever want to see what the bot has actually been calling. Per-server restriction of a key is enforced by the platform but is not offered on the create form, so ask support if you want the bot's key limited to one community's servers.

Console output is redacted

Console and log output that the bot shows - through /console, /command and the live channel mirrors - is filtered before it is posted. Credentials and network addresses are replaced with [REDACTED], including a setting whose name merely contains a word like password, token, secret or api key (for example a telnet password or an admin password line), and a password typed after the word with a space. The same filter is applied to what the log channel records about a command, so a password typed into /command is not kept. The bot also never pings anyone from a mirrored line.

The setting name is kept and only the value is replaced, so a line still reads rcon_password=[REDACTED] and you can see that the setting exists.

If you see [REDACTED] or [ip-hidden] where a player's IP address would be in a join message, that is working as intended, not a bug. Player IP addresses are never shown to server owners: GameGrid masks them as [ip-hidden] in the panel console, command replies, the Customer API and downloaded logs as well, so there is no unmasked copy to look up.

One deliberate gap: /preset view redacts credential-looking values but not IP addresses, because a game version number like 1.20.4.1 matches the shape of an IPv4 address and would otherwise be hidden.

Channel and visibility controls

Discord permissions still apply on top of everything above. The bot can only read and post in channels its own Discord role allows, so the ordinary way to limit who sees what is to put the bot in a private channel.

Beyond that:

• `/config command-channel` restricts /command - and only /command - to a single channel. Other commands are unaffected, including /console.
• Reply visibility is fixed per command, not configurable. Anything that could leak a credential or a private balance replies privately: /console, /command, /balance, /buy, /daily, /link, /my-transactions, /account, /billing, /tickets, /backups restore, /settings set, every /settings table change and /settings table show-password, /economy-links, every `/command-schedule` subcommand, every /preset and /event subcommand and every /config subcommand. Status and lifecycle commands reply publicly so the channel can see who restarted the server.
• Live mirrors post to whichever channel you point them at. Anyone who can read that channel sees the console, subject to the redaction above. Point them at a private channel.
• The log channel records who ran what. Set it with /config log-channel and give your admins read access to it. Every /config change and every command that changes something in GameGrid is recorded there.

Removing the bot

Two options, and they do different things.

`/config reset` clears the bot's configuration for your Discord server - the stored key, role grants, channel bindings and live mirrors - while leaving the bot in the server. Use it to start clean. It asks for confirmation first, and only the setup user or the server owner can confirm.

Removing the bot from your Discord server deletes its configuration for that server automatically.

Neither touches your API key. Revoke the key in the panel as well if you are removing the bot for good - see API Key Management.