How to Set Up a Discord Whitelist for Your FiveM Server (…

Audience: FiveM server owners & developers
Difficulty: Easy → Intermediate
Outcome: Role‑based allowlist using Discord roles (with optional blacklist), minimal maintenance, clear player feedback.

Note on versions: The open‑source repo FAXES/DiscordWhitelist is community‑maintained and last updated in 2022. It still works for many servers. A maintained commercial version exists; if you need support/SLA, consider it. This guide covers the free GitHub version.

---

TL;DR

1. Create a Discord Bot → enable Server Members Intent → invite it to your Discord.
2. Copy your Guild (Server) ID and Role ID(s).
3. Download: FAXES/DiscordWhitelist on GitHub → put it in resources/ → configure server.js.
4. Add ensure DiscordWhitelist to server.cfg (or start in txAdmin).
5. Test: join without the role (blocked) → add role → rejoin (allowed).

Related tutorials:
• FiveM Whitelist — Complete Guide (txAdmin, Scripts, DB)
• How to Create Discord Donation Tiers

---

Why Discord‑based Whitelisting?

• Dynamic: Grant/deny access by adding/removing a Discord role—no ACE or DB edits.
• Scalable: Mods can manage access from Discord on mobile.
• Auditable: Role history + moderation logs show who allowed whom.

---

Prerequisites

• A Discord server (you are Admin/Owner).
• FiveM server with txAdmin or manual control.
• Players must have the Discord desktop app running when connecting (so FiveM exposes a discord: identifier).

---

Step 1 — Create a Discord Bot & Enable Intents

1. Go to the Discord Developer Portal → New Application → name it (e.g., FiveMX Whitelist Bot).
2. Add a Bot (Bot tab) → Reset Token → copy the Bot Token (store it securely).
3. Under Privileged Gateway Intents, enable Server Members Intent. (Presence intent is not required.)
4. Invite the Bot to your Discord: OAuth2 → URL Generator → Scopes: bot; Permissions: minimal (can be none beyond joining). Use the generated URL and add it to your guild.

Security: Treat the Bot Token like a password. Do not commit it to Git or share it in screenshots. Rotate if leaked.

---

Step 2 — Get Your IDs (Guild & Roles)

• In Discord → User Settings → Advanced → Developer Mode: ON.
• Right‑click your server name → Copy Server ID.
• Server Settings → Roles → right‑click the role you’ll use as the whitelist (e.g., Whitelisted) → Copy Role ID.
• (Optional) Copy IDs for any roles you want to blacklist (e.g., Banned).

Keep these handy:

• GUILD_ID = 123456789012345678
• WHITELIST_ROLE_IDS = ["111111111111111111", "222222222222222222"]
• BLACKLIST_ROLE_IDS = ["333333333333333333"]

---

Step 3 — Download & Install the Resource

1. Download the ZIP from FAXES/DiscordWhitelist (GitHub).
2. Extract to your server at:
   resources/[discord]/DiscordWhitelist
3. Verify the folder contains at least:
   • fxmanifest.lua
   • server.js
   • package.json

server.cfg (or txAdmin Recipe / Startup):

# Start after your identifier providers and before join‑logic that depends on it
ensure DiscordWhitelist

In txAdmin → Resources, mark DiscordWhitelist to start on boot (if you manage resources via UI).

Planning your access strategy? Read our broader guide: FiveM Whitelist — Complete Guide (txAdmin, Scripts, DB) for alternatives (ACE, DB, hybrid) and when to use each.

---

Step 4 — Configure server.js

Open resources/[discord]/DiscordWhitelist/server.js and set the config block. The file may already expose a simple config object—adjust values accordingly. A typical configuration looks like this:

// DiscordWhitelist configuration — example
const config = {
  botToken: "PASTE_YOUR_DISCORD_BOT_TOKEN_HERE",
  guildId: "123456789012345678",               // Your server (guild) ID

  // Players must have at least ONE of these role IDs to join
  whitelistRoles: [
    "111111111111111111", // Whitelisted
    // "222222222222222222", // Staff (optional)
  ],

  // If a player has ANY of these roles, reject the connection
  blacklistRoles: [
    // "333333333333333333", // Banned
  ],

  // Cache fetched role data to reduce Discord API calls (seconds)
  cacheMaxTime: 90,

  // Deferral messages
  messages: {
    noDiscord: "Open Discord and rejoin. Your Discord app must be running.",
    notWhitelisted: "You are not whitelisted. Join our Discord: discord.gg/yourinvite",
    blacklisted: "Access denied. Please contact staff.",
    welcome: "Welcome — you are verified. Loading…"
  },
};

Monetization tip: If your server uses perks, pair this with Discord Donation Tiers to automate role‑based benefits for supporters/donors.

Save the file.

---

Step 5 — Restart & Test

1. Restart just the resource or the whole server: txAdmin → Restart resource or console refresh then restart DiscordWhitelist.
2. Negative test: Try connecting without the whitelist role → you should see the deferral message and be kicked.
3. Positive test: Grant yourself the whitelist role → reconnect → you should be allowed in.

---

Optional: Multiple Roles & Staff Bypass

• Add several whitelist roles to allow multiple funnels (e.g., Donator, Police, EMS).
• Add blacklist roles for hard blocks regardless of whitelist (e.g., Banned).
• You can include a staff role in whitelistRoles to guarantee access for admins.

---

Operational Tips

• Automation: Connect Discord role assignment to your application forms or ticket approvals (e.g., with a bot, Google Forms → webhook → role add).
• Player UX: Pin a #how-to-whitelist post with ✅ role requirements and your server invite.
• Moderation: Log role changes in a private #mod-logs channel.

---

Troubleshooting

“Bot offline” or never updates roles

• Token wrong or bot not invited to the correct guild.
• Server Members Intent not enabled.
• Firewall blocks outbound HTTPS from your game host (allow Discord API).

“No Discord identifier found” / everyone blocked

• Players must run the Discord desktop app before launching FiveM. Ask them to restart Discord, then FiveM.

Role changes only apply after a restart

• Reduce cacheMaxTime to 30–60 seconds.
• If you set it extremely low and still see delays, check rate limits and avoid restarting frequently.

403/Permissions error when fetching guild members

• Ensure the bot is in the target guild and Server Members Intent is enabled.
• The bot does not need Admin perms to read member roles.

High API usage / rate limiting

• Increase cacheMaxTime. Avoid mass‑kicking/restarts that spam API calls.

---

Security Best Practices

• Store the Bot Token outside of version control. If you self‑host configs, consider reading it from an environment variable or server.cfg convar, not in plain text committed to Git.
• Rotate the token if leaked.
• Restrict who has write access to the resource.

---

Uninstall / Disable

• Remove ensure DiscordWhitelist from server.cfg (or disable in txAdmin → Resources).
• Remove the folder from resources/ if you’re decommissioning it.

---

FAQ

Do players need Discord running?
Yes. Without the discord: identifier, the script can’t verify roles.

Which intents do I need?
Only Server Members Intent.

Can I use multiple whitelist roles?
Yes. Access is granted if the user has any of the listed roles.

Can I hard‑deny certain roles?
Yes. Add them to blacklistRoles.

It stopped working after I changed roles.
Lower cacheMaxTime, then test again. Ensure the bot is online with the correct token and guild.

Is there a maintained version?
Yes. A commercial, actively maintained edition exists if you need updates/support.

---

Appendix — Example server.cfg

# Discord whitelist
ensure DiscordWhitelist

# (Optional) put related Discord resources here as a block
# ensure discord_perms
# ensure discordrolesync

Appendix — Example Player Messaging (Deferrals)

Keep messages short and actionable:

messages: {
  noDiscord: "Open Discord and rejoin. Your Discord app must be running.",
  notWhitelisted: "Not whitelisted. Apply in #how-to-whitelist → discord.gg/yourinvite",
  blacklisted: "Access denied. Contact staff via ticket.",
  welcome: "Verified — loading city…"
}

---

Changelog (Editor‑facing)

• v1.1 — Added natural internal links to Donation Tiers, FiveM Whitelist Complete Guide, and GitHub download.
• v1.0 — Initial guide: bot creation, intents, IDs, install, config, testing, FAQ.