Running keys
Pools
A pool is a named batch of keys for one game, plus the rules for handing them out. Pools are per server, and a server can run as many as it needs.
Pool settings
| Setting | Effect |
|---|---|
| Name | Identifies the pool. Two pools in the same server cannot share a name. Members pick it from the /claim autocomplete, which shows it as name (game), so short and typable beats descriptive. |
| Game | The display name shown to members. Claimed keys are grouped by game, so two pools for the same game appear together in a member's key list. |
| Key type | Steam or Custom. See below. |
| Public or private | Private pools reject every /claim with "Keys for this game are private." Moderator grants still work, which makes a private pool the way to run a grant-only drop. |
| Keys per user | How many keys one member may claim from this pool, from 0 to 300. Counted per pool, not per server. |
| Required roles | A member must hold every role in the list to claim. An empty list means anyone in the server may claim. |
| Moderator roles | Who may run /grant on this pool. The caller must hold every role in the list. An empty list means /grant cannot be used on this pool at all. |
Steam keys and custom keys
A Steam pool delivers each key alongside a Steam activation link, so the member can redeem in one click. A Custom pool delivers the key as plain text and nothing else, which is right for itch.io codes, Epic codes, GOG codes, beta invites, or anything that is not a Steam product key.
The type is a property of the pool, and every key imported into it inherits that type. If you have both Steam and non-Steam codes for the same game, use two pools.
Public and private
Visibility is the on and off switch for a drop. Making a pool private stops self-claiming immediately and does not touch the keys already in it, so it is safe to flip back and forth. Useful moments to go private:
- While you are importing keys and setting up role gates.
- When a drop should open at a specific time.
- For a pool that only ever goes out through moderator grants, for example press keys or creator codes.
Keys per user
The limit counts how many keys that member has already claimed from this pool. Once they reach it, further claims are refused with a message naming the limit.
/grantrespects the limit. Granting to someone who has already hit it will be refused./grantroledoes not check the limit. A bulk grant to a role gives one key to every member holding it, whatever they have claimed before.- Setting the limit to 0 means nobody can self-claim, even from a public pool. That is a deliberate option, not an error, but it is easy to set by accident.
Required roles and moderator roles
Required roles gate claiming. The check is an AND, not an OR: a member needs all of them. If a claim is refused, KeyBot names the roles they are missing, so it is obvious what to fix.
Moderator roles gate /grant for that pool, and they are also an AND. This is separate from Discord permissions on purpose: it lets you give a partner, a community manager, or an event host the ability to hand out keys from one specific pool without giving them Manage Server.
Stock warnings
If your server has a warning channel configured, KeyBot posts there when a pool is running out. There are two notices and each fires once:
| Notice | Fires when |
|---|---|
| Key Pool Low | Unclaimed keys fall to ten percent or less of the pool total. |
| Key Pool Empty! | A claim is attempted and there are no unclaimed keys left. |
Both are checked when a member claims and again after a bulk grant, so a /grantrole that drains a pool still raises the alarm. A successful key import clears the flag, so the next time the pool runs low you get told again.