Server Admin Guide

Everything you need to get GateKeepr running on your Discord server. No code. No hosting. Configure it through slash commands inside Discord, or click through the web dashboard — the same settings, two different surfaces.

What You'll Need

• Manage Server permission on the Discord server you want to protect.
• About 10–15 minutes.

Step 1 — Invite the Bot

1. Click Invite to your server (or use the button on the home page).
2. Select your server from the dropdown.
3. Leave all the requested permissions checked and click Authorize.
4. Complete the CAPTCHA if Discord shows one.

The bot should now appear in your server's member list.

Step 2 — Prepare Your Server

2.1 — Turn on Developer Mode (optional but handy)

User Settings → Advanced → Developer Mode: ON. Lets you right-click to copy role/channel IDs if you ever need them.

2.2 — Create the Verified role

Server Settings → Roles → Create Role. Name it whatever you want (Verified and Member are common choices). Don't give it any special permissions yet — you'll configure channel visibility in Step 4.

2.3 — Fix role hierarchy (IMPORTANT)

In Server Settings → Roles, drag the bot's role above the Verified role. If you plan to use Patreon auto-verify, the bot's role must also be above your Patreon tier roles.

Admin
Moderator
GateKeepr       ← bot's role (must be above everything it manages)
Patreon tiers
Verified
@everyone

If the bot's role sits below a role it's trying to assign, Discord blocks it and verification silently fails.

2.4 — Create your channels

• #verify — the channel where the Verify button will live. New joiners must be able to see this.
• #mod-log (optional) — where verification events get logged. Make this mod-only.

Step 3 — Configure the Bot

All configuration happens through slash commands. You need Administrator permission to run any of them.

3.1 — Required settings

Run these three in your server:

/set-verified-role role:@Verified
/set-verify-channel channel:#verify
/set-log-channel channel:#mod-log

The log channel is optional — skip it if you don't want event logging.

When set, the log channel receives color-coded embeds for: verification attempts (started, succeeded, failed, kicked), Patreon auto-verifies, grandfather passes, and every admin command your mods use (a paper trail for who changed what). If the admin-command log is noisy, disable it with /set-admin-logs enabled:false — the rest of the event logging keeps working.

3.2 — Patreon auto-verify (optional)

If you have Patreon tier roles and want paying supporters to skip the CAPTCHA entirely:

/patreon-add role:@Patron
/patreon-add role:@VIP

Add as many tier roles as you want. Anyone who already has one of these roles when they join — or who receives one later — gets auto-verified. No button click, no CAPTCHA.

3.3 — Tune difficulty (optional)

Defaults are sensible. Change only if you need to:

/set-captcha-length length:6
/set-cooldown seconds:30
/set-max-attempts attempts:3

3.4 — Check your work

Run /settings anytime to see every setting for your server in one place.

Step 4 — Launch Verification (Order Matters)

4.1 — Post the Verify button

Anywhere in your server, run:

/setup-verify

A green embed with a Verify button appears in your configured verify channel. This is the button new joiners will click.

4.2 — Grandfather your existing members

Anywhere in the server, run:

/grandfather

This bulk-assigns the Verified role to every existing non-bot member. Bots are skipped. Already-verified members are skipped.

On larger servers this takes a while — budget roughly 1 minute per 60 members. You'll see a progress update in the log channel (if set) and a completion summary when done.

4.3 — Lock down channel permissions

Only now should you lock down channel permissions. The easy way: run /lockdown in your server.

GateKeepr will scan every channel, show you a preview of what it's about to do (with the role names spelled out), and wait for you to click Confirm before changing anything. It denies @everyone view permission on public channels, allows your Verified role and any configured Patreon roles, and leaves #verify visible to everyone. Already-private channels (mod-only, etc.) are skipped automatically. Mistakes are reversible with /lockdown-undo.

Prefer to do it by hand? You can skip admin entirely and set the overwrites yourself:

• @everyone → View Channel: ❌ on every non-verify channel
• Verified → View Channel: ✅ on every non-verify channel
• Each Patreon role from your settings → View Channel: ✅ on every non-verify channel
• #verify → leave @everyone set to View Channel: ✅

Done.

New joiners see only #verify, click Verify, solve the CAPTCHA, and get the Verified role. Existing members keep their access. Patrons get in automatically.

Invite Tracking & Ban Attribution

GateKeepr records which invite link each new member used and who created that invite. Combined with ban tracking, this lets you answer questions like "who's been inviting all these spammers?" without guesswork.

What gets logged automatically

When a user joins:

• The invite code they used
• Who created that invite
• Which channel the invite pointed to
• Timestamp

When a user is banned (by anyone, including other mod bots):

• Who did the ban and why (pulled from the audit log when available)
• The invite history attached — "originally joined via abc123, created by Bob"
• If 5 bans have happened from the same invite, the bot auto-deletes that invite and flags it in the log. Threshold configurable with /set-invite-autodisable.

Useful investigator commands

/invite-stats — dashboard view with top inviters, total joins tracked, how many bans you've had, and how many invites were auto-disabled.

/invite-audit code:abc123 — see every user who joined through a specific invite code, with 🔨 marks next to anyone who was later banned. Useful when you suspect one invite leaked to a raid channel.

/inviter-score user:@Bob — summary for one person: how many people they've invited, how many got banned, ban rate percentage. Helps identify compromised accounts or members being careless with invite links.

Privacy defaults

Inviter DM notifications are OFF by default. If you enable them with /set-inviter-notifications enabled:true, the bot will DM someone when a user they invited gets banned. Some communities find this helpful ("hey, be careful who you share your invite with"), but DMing strangers is invasive by default — so it's opt-in.

Edge cases honestly explained

• Vanity URLs (discord.gg/your-name) are tracked as (vanity:your-name) when the bot can't match a regular invite.
• Server discovery joins can't be attributed to an invite. Logged as "invite source could not be determined."
• Bot restarts reset the in-memory invite cache. The first person to join within the next second or two may show as "unknown" until the cache rebuilds.
• Two people joining at the same moment can occasionally both be attributed to the same invite. Rare, not a real problem.

Your Data — Export, Wipe, Retention

Every server's data is stored in its own SQLite file on the bot's host. No server can see another server's data. When GateKeepr is removed from your server, the file is deleted entirely — no orphaned data.

Export your data anytime

/export-data sends you an ephemeral Discord message with a JSON attachment containing every piece of data the bot has stored for your server: settings, join history, ban records, and auto-disabled invites. Useful for backups, audits, or migrating to self-hosted.

Wipe tracking history while keeping settings

/clear-invite-data confirm:true wipes all join records, ban records, and disabled-invite flags for your server — but keeps your verification settings (verified role, verify channel, CAPTCHA config, etc.) completely intact. Useful if you want a clean slate after a long-running incident without reconfiguring the bot.

The confirm:true argument is required. Running /clear-invite-data confirm:false does nothing — it's a safeguard against accidental taps.

Retention policy

By default, join records older than 12 months are auto-pruned once per day. Ban records are kept forever regardless — mod logs shouldn't silently disappear. Configure retention with /set-retention months:6 (anything 1–120), or set months:0 to keep join records forever too.

What happens if I kick the bot?

The bot's on_guild_remove handler deletes your server's DB file. If you re-invite the bot later, it's a fresh start — no ghost data from before.

All Slash Commands

Every command requires Administrator permission.

All Settings You Can Change

Each server has its own independent settings. Changing a setting on one server never affects another.

Testing Checklist

Before you tell your members to join, test the flow yourself:

• Bot is online (green dot in member list).
• /settings shows your Verified role, verify channel, and (optionally) log channel set correctly.
• The /setup-verify embed is posted in #verify with a visible Verify button.
• Join with an alt account (or ask a trusted friend). They should:
  • Only see #verify on join.
  • Click Verify → get a CAPTCHA image in an ephemeral message.
  • Click "Enter Answer" → submit the text → get the Verified role.
  • Now see the rest of the server.
• Check the log channel — verification events (started, verified, failed, kicked) should appear.
• If using Patreon: give your alt a Patreon role, they should auto-verify with no button click.
• Try typing the wrong CAPTCHA on purpose max-attempts times. The bot should kick (if max-attempts > 0).

Troubleshooting

"The bot can't assign the Verified role."

Role hierarchy problem. Drag the bot's role above the Verified role in Server Settings → Roles.

Verify button does nothing when clicked.

Either the bot is offline (check the green dot), or @everyone has Use Application Commands: ❌ in that channel. Re-enable it, or just leave the channel at default permissions.

The Verify embed never appeared after /setup-verify.

The bot is missing Embed Links permission in that channel. Check channel permissions or re-invite the bot using the original invite link.

Slash commands don't show up at all.

The first time a bot joins a server, slash commands can take up to an hour to propagate globally. If they're still missing after that, re-invite the bot with the original invite link.

Existing members got locked out.

You locked channel permissions before running /grandfather. Fix: temporarily re-grant @everyone view access, run /grandfather, then re-lock. Or manually assign the Verified role to yourself and a few mods and grandfather from there.

Patreon users have to solve the CAPTCHA anyway.

Either you forgot to /patreon-add their tier role, or the bot's role is below that Patreon role. Fix the hierarchy and re-run the command if needed.

CAPTCHA image doesn't load.

Almost always a user-side issue — Discord's CDN blip or their client blocking the ephemeral attachment. Have them click Verify again.

I changed a setting but nothing seems different.

Most settings apply to the next verification attempt, not ongoing ones. Have the test user click Verify again.

I need to start over.

Run /reset-settings. That wipes every setting for your server. Existing Verified role assignments stay intact — only the bot's configuration is cleared.