How to Set Up a Discord Whitelist for Your FiveM Server (2026 Guide)
Gate access to your FiveM server with a Discord role-based whitelist. Covers three implementation approaches (pure Discord, identifier-based, hybrid), step-by-step bot setup, working QBCore and ESX examples, common mistakes that break auth, and security hardening.
A Discord whitelist gates access to your FiveM server using Discord roles. Players without the right role can't join, moderators can grant or revoke access from their phone via a role toggle, and every grant is logged in Discord's audit trail.
This guide covers three implementation approaches, step-by-step bot setup, working configurations for both QBCore and ESX, common mistakes that silently break auth, and security hardening for production servers.
Note on versions: The open-source
FAXES/DiscordWhitelistrepo is community-maintained and last updated in 2022. It still works for most servers. Several commercial forks exist with active maintenance and SLA support. This guide covers the free GitHub version and the patterns apply to any Discord-based whitelist.
TL;DR
- Create a Discord Bot in the Developer Portal → enable Server Members Intent → invite to your guild.
- Copy your Guild (Server) ID and Role ID(s).
- Download FAXES/DiscordWhitelist into
resources/and configureserver.js. - Add
ensure DiscordWhitelisttoserver.cfg. - Test: join without the role (blocked), grant the role, rejoin (allowed).
Three Whitelist Approaches: Which One Fits Your Server?
Before picking an implementation, decide which of these three approaches matches your operational reality:
| Approach | How it works | Pros | Cons | Best for | |
Frequently Asked Questions
Why use Discord for whitelisting a FiveM server?
Discord whitelisting is dynamic (grant access by adding a role, no ACE or DB edits), scalable (moderators can manage access from mobile Discord), and auditable (Discord role history + audit logs show who granted what). The main trade-off vs identifier-based whitelisting is that players must have the Discord desktop app running when connecting, which makes Discord the hard dependency for joining your server.
Which whitelist approach should I pick: pure Discord, identifier-based, or hybrid?
Pure Discord role check is simplest and best for servers under 500 concurrent players — one Discord role controls everything. Identifier-based (SQL table of allowed Steam/license IDs) is most secure and independent of Discord, at the cost of manual list management. Hybrid combines both: Discord role for most players, identifier whitelist as break-glass for VIPs/admins when Discord API is down. Hybrid is the right answer for serious servers.
What do I need to set up a Discord whitelist?
Four things: (1) a Discord server where you're admin, (2) a FiveM server with txAdmin or CLI access, (3) players running the Discord desktop app before launching FiveM (so FiveM exposes the discord: identifier), and (4) a bot created in the Discord Developer Portal with the Server Members Intent enabled.
How do I fix the 'Bot offline' error?
Three causes: wrong bot token in config, bot not actually invited to the guild, or the Server Members Intent wasn't enabled in the Developer Portal. Verify the token starts with the correct prefix, check that the bot appears in your Discord member list (offline is fine, not-present is not), and confirm both Intents in the Bot tab of the Developer Portal: Server Members Intent ON, Presence Intent can stay OFF.
Players are blocked even when they have the whitelist role. What's wrong?
The most common cause is the Discord desktop app not running when the player launches FiveM — without it, FiveM can't expose a discord: identifier to the script. Have the player restart Discord, wait for it to fully load, then launch FiveM. If that doesn't fix it, the bot's guild-members cache is stale — reduce cacheMaxTime in the config from 90s to 30s.
Can I use multiple whitelist roles (Donator, Staff, Applied)?
Yes. Add every role ID to the whitelistRoles array in the config. Access is granted if the player has any one of the listed roles. This is how most servers handle funnel differentiation — one role for approved applicants, another for donators, a third for staff with automatic access.
How do I prevent race conditions where role changes take minutes to apply?
Two things: lower cacheMaxTime to 30-60 seconds so the bot refreshes role data more often, and if you need instant updates, implement a webhook on the Discord role-change event that invalidates the cache immediately. Without the webhook, players who just received a role will be denied until the next cache refresh — annoying but usually not worth the implementation effort unless you have high applicant churn.
Is Discord whitelisting secure against bypass attempts?
The weak link is the bot token. If it leaks, attackers can impersonate the bot, read your guild member list, and potentially inject themselves into the whitelist. Store the token outside version control (env var or convar), rotate if leaked, and restrict who has write access to the resource folder. For high-value servers, pair Discord whitelisting with an identifier-based fallback — that way even a complete Discord compromise doesn't grant server access.
