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.

This guide is part of our complete FiveM server management hub, covering everything from initial setup to scaling your community.

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.