Setting up Discord roles

What you are actually setting up

The GameGrid bot binds what it will do to your own Discord roles — Verified, Regular, Veteran, Helpers, whatever you already call them. You never invent a GameGrid role and you never type a role ID; you pick a role out of Discord's own role picker and say what it may do.

What a role may do is a set of named abilities, not a rank. There are 49 of them, arranged in 15 groups — servers, settings, console and logs, players and files, in-game, backups, mods, Windrose Plus, events, scheduled commands, the economy and its admin side, the chat bridge, account and billing, and the bot's own permissions. server.restart and settings.write are two different abilities, so "the moderators may bounce a stuck server but may not change the difficulty" is a thing you can say.

Two rules decide everything else, and both are covered below: several roles add up, and your API key is the ceiling over all of them.

Every role starts with nothing. A role you have never touched grants no bot access at all, so there is no unsafe default to remember to lock down.

Role setup in five steps

You need /setup to have been run already — the bot needs a linked API key before any of this means anything. See the Discord Bot Setup Guide if you have not got that far.

1. See what there is to give. /permissions catalogue lists all 49 abilities, grouped. /permissions list shows every Discord role and what it currently holds. Both are safe to run at any time.

2. Start a role from a preset. Pick the nearest ready-made set rather than granting 20 things one at a time.

/permissions preset role:@Moderators preset:moderator
/permissions preset role:@Members preset:member

3. Adjust from there, one ability at a time. A preset is a starting point, not a cage.

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

The capability box autocompletes — start typing backup or restart and it offers the matching abilities, so you do not have to memorise the names.

4. Check the ceiling. /permissions key shows what the API key behind the bot allows, and therefore which abilities are unreachable no matter what you grant. Do this before you go hunting for a role problem that is really a key problem.

5. Read it back. /permissions role role:@Helpers shows exactly what one role carries. /permissions me shows what you personally can do, which is the union of all your roles, after the ceiling has been applied.

To take everything away from a role in one go, /permissions clear role:@OldRole.

The five presets

Presets are ready-made sets of abilities. There are five, and each is a superset of the one above it.

A preset is resolved when you apply it, into the explicit list of abilities it contained at that moment. It does not quietly widen later when a new ability is added to the bot. There is deliberately no wildcard and no "everything" ability: a grant that grows on its own is the commonest way a Discord ends up allowing something nobody meant to allow.

So applying moderator today and granting one more ability tomorrow leaves a role holding 42 named abilities, and /permissions role will list all 42. What a role holds is always an auditable list, never a rule.

Several roles add up: the union, never the strongest one

A member holding Verified and Minecraft Player and Regular can do everything any of those three grants. The sets are added together.

This is how Discord's own permissions work, and it is the part people most often get backwards. It means:

• A role never takes away what another role gave. Granting @Veteran the shop and @Moderators the console gives a moderating veteran both.
• The order your roles sit in on Discord's settings page makes no difference here. That order decides display colour and who may manage whom; it does not decide what this bot allows.
• There are deliberately no denials. To take an ability away you revoke it from the role that grants it. /permissions list then shows you, in one screen, why anybody can do anything.

If someone can do more than you expected, the answer is almost always a second role you had forgotten they hold. /permissions me, run by them, is the quickest way to see it.

Your API key is the ceiling

Everything the bot does is signed with the one GameGrid API key you linked with /setup. That key carries a fixed set of API scopes, chosen when you minted it in the customer panel.

A Discord role therefore grants a subset of what that key already allows — never a superset, and never more. If the key does not carry servers:lifecycle, nobody restarts a server through this bot: not a role holding all 49 abilities, not the person who ran /setup, and not the Discord server owner. The ceiling is checked before any of those.

That makes the two refusals different problems with different fixes, so the bot words them differently on purpose:

When both are missing the bot names the key, because granting the role would change nothing while the key still cannot back the request.

Run /permissions key to see what your key allows, and /permissions refresh-key after minting a new one. API Scopes and Permissions lists every scope; API Key Management covers minting and rotating them.

What @everyone may hold

@everyone is a real Discord role whose members include every person who walks in through a public invite. The bot will not let you grant it anything destructive, and nothing at all under Account & billing, no matter what you type.

What @everyone may hold is exactly the 21 abilities in the member preset: viewing servers and settings, reading logs and player lists, the live map, who is online and the kill feed on games that report them, and the player side of the economy — checking your own balance, browsing the shop, buying, browsing and claiming kits, the daily bonus, and linking your own account.

That is a sensible default for a public gaming Discord. /permissions preset role:@everyone preset:member is a reasonable first move, and it is the only preset @everyone will accept.

Who may grant roles

Three kinds of person can change these grants:

• The Discord server owner.
• Whoever ran `/setup`.
• Anyone holding the `bot.permissions.manage` ability, which is in the admin preset.

That last one is the delegation you want if you do not intend to be the only person who can hand out access. Grant it to your head admin's role and they can run /permissions without ever seeing your API key.

bot.permissions.manage cannot lift the ceiling. Someone holding it may grant any ability, but an ability the API key cannot back stays unusable for everybody. Handing out permissions and handing out scopes are two different powers, and only the second one lives in the customer panel.

/permissions me and /permissions catalogue are deliberately open to everybody — "what may I do, and what is there to ask for" should not itself need permission.

Destructive abilities, and being deliberate about them

20 of the 49 abilities are marked destructive: they stop a server, overwrite data, change configuration or spend currency. /permissions list calls them out in red.

None of them is in the member preset, which is why member is safe to give a whole community. They start at operator (the console) and moderator (stopping and restarting, settings, restoring and deleting backups, mods, events, economy administration).

The two worth pausing over before you grant them are backups.restore, which writes a backup over the live world and loses everything since, and server.stop, which disconnects everyone. Note that server.start is a separate ability from both — "let them bring it back up after a crash" does not have to mean "let them take it down".

Discord Bot Permissions & Security lists all 49 abilities by name, with the scope each one needs and which are destructive.

When someone is refused

Work through it in this order. It takes about a minute and saves an afternoon.

1. Read the refusal. It names either an ability or a scope. Those are different problems — see the ceiling section above.

2. Have them run `/permissions me`. This is what they can actually do, after the key ceiling. If the ability is missing here but you believe you granted it, the key is the reason.

3. Run `/permissions role role:@TheRole`. Confirms the grant actually landed on the role you thought.

4. Check they hold that role. In Discord, not in your memory.

5. Run `/permissions key`. If the ability is listed as unavailable, stop editing roles: mint a key with the missing scope and re-run /setup.

Re-running /setup with a different key clears every role grant, channel binding and live stream, because the old grants were made against an API key that no longer applies. Re-apply your presets afterwards. Re-running /setup with the same key leaves them alone.

The old access levels are gone

The bot used to give a Discord role one position on a single ladder, and every command demanded a minimum rung. If you have read older notes, forum posts or screenshots describing that, they are out of date.

Two things changed that are worth knowing if you set your server up under the old model:

• A rank became a set. Abilities that used to share a rung — restarting a server and changing its settings, for instance — are separate grants now, so you can give one without the other.
• Roles combine by union. Anything you read that says a member gets whatever their strongest role carries is describing the old behaviour and understates what a member with two roles can do.

Nothing you configured was lost. A role that still carries an old-style setting keeps exactly the access it had: it resolves to the matching preset, and the two styles mix freely, so you can convert one role at a time with /permissions preset rather than redoing your whole Discord at once.