FiveM Whitelist — Complete Guide (txAdmin, Scripts, DB)

Introduction to A whitelist in FiveM is an access-control mechanism

A whitelist in FiveM is an access-control mechanism that restricts server entry to pre‑approved players, matched by their unique identifiers (Rockstar license, Steam ID, Discord ID, etc.). Below is a production‑ready guide covering txAdmin’s built‑in whitelist, script patterns, database storage, and reliability notes.

---

TL;DR Options Matrix

Mode

Where to set

What it checks

Best for

Notes

Approved License

txAdmin → Settings → Player Manager → Whitelist Mode

license: (Rockstar)

Most servers

Simple, reliable; manual approvals or pre‑approvals supported

Discord Member

txAdmin (Discord linked)

discord: is guild member

Communities centered on Discord

Non‑Discord users blocked

Discord Role

txAdmin (Discord linked)

discord: has specific role

Role‑gated access (donor, staff)

Combine with role automations

Admin‑only

txAdmin

Admins only

Maintenance/dev nights

Effectively locks server, not recommended

Custom Script

Lua/JS resource

Any identifiers you want

Granular rules & UX

Needs code + upkeep

Recommendation: Use Approved License for the baseline (everyone has a Rockstar license), then add Discord Role as an extra gate for special tiers.

How to create a Whitelist

Create Whitelist using Discord

---

How to Enable & Operate Whitelist in txAdmin

Prerequisites

• txAdmin running (shipped with FXServer).
• For Discord modes: Discord integration configured (bot invited, guild/role selected).

Enable whitelist

1. Open txAdmin → Settings → Player Manager.
2. Set Whitelist Mode to one of: Approved License, Discord Member, Discord Role, or Admin‑only.
3. Set a Rejection Message, e.g.:
   Not whitelisted. Apply at discord.gg/yourinvite
4. Save.

Approve players (two flows)

• Passive (queue): When a non‑approved player tries to join, a request appears under Whitelist. Approve/deny with one click.
• Active (pre‑approve): Go to Whitelist → Add Approval and paste an identifier in the form type:value, e.g.

  • license:110000112345678

  • steam:11000010abcdef0

  • discord:123456789012345678

    Revoke

    • Open Players or Whitelist and click Revoke next to the approval.

    Tips

    • Prefer license identifiers for baseline access (universally present).
    • Keep your rejection message actionable (Discord link + basic rules + ticket CTA).
    • For staff/devs, stack requirements: e.g., must be license + discord role.

    ---

    Technical Implementation Details

    Whitelists run during the connection deferral stage

    Whitelists run during the connection deferral stage. The server inspects the player’s identifier set and accepts or rejects before resources load. This keeps load low and blocks non‑approved players early.

    Identifier Types (reliability)

    • license: (Rockstar) — stable, tied to game purchase; recommended primary key.
    • steam: — present only if Steam runs; can be missing if players do not use Steam.
    • discord: — present only if Discord runs and your server reads it.
    • ip: — dynamic; use for telemetry/rate‑limit, not identity.

    ---

    Minimal Whitelist Script (deferrals UX + multi‑ID)

    -- resource: simple-whitelist -- fxmanifest.lua should include '@oxmysql/lib/MySQL.lua' if you use DB code below.

    local STATIC_WHITELIST = { > ["license:110000112345678"] = true, ["steam:11000010abcdef0"] = true, ["discord:123456789012345678"] = true, }

    local function collectIdentifiers(src) local ids = {} for _, id in ipairs(GetPlayerIdentifiers(src)) do ids[id] = true end return ids end

    AddEventHandler("playerConnecting", function(name, setKickReason, deferrals) local src = source deferrals.defer() deferrals.update(("Checking whitelist for %s..."):format(name))

    local ids = collectIdentifiers(src)

    -- Require at least a Rockstar license in all cases local hasLicense = false for id, _ in pairs(ids) do if id:sub(1, 8) == "license:" then hasLicense = true break end end if not hasLicense then return deferrals.done("You must start the game normally (Rockstar license missing). Restart and try again.") end

    -- Static allowlist quick‑path for id, _ in pairs(ids) do if STATIC_WHITELIST[id] then return deferrals.done() end end

    -- Fallback: not approved return deferrals.done("Not whitelisted. Apply at discord.gg/yourinvite") end)

    Use deferrals.update to show progress messages while

    Use deferrals.update to show progress messages while you check IDs and/or a database. This reduces false “timeout” reports.

    ---

    Database‑Driven Whitelist (oxmysql, production‑ready)

    Schema

    CREATE TABLE IF NOT EXISTS whitelist ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, identifier VARCHAR(64) NOT NULL, note VARCHAR(120) NULL, added_by VARCHAR(64) NULL, added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY u_identifier (identifier) );

    Server‑side check (oxmysql)

    -- Requires oxmysql. Add to fxmanifest: '@oxmysql/lib/MySQL.lua' AddEventHandler('playerConnecting', function(name, setKickReason, deferrals) local src = source deferrals.defer() deferrals.update('Verifying whitelist...')

    local ids = {} for _, id in ipairs(GetPlayerIdentifiers(src)) do table.insert(ids, id) end

    -- Single scalar: any identifier approved? local rowCount = MySQL.scalar.await( 'SELECT COUNT(*) FROM whitelist WHERE identifier IN (?)', { ids } )

    if rowCount and rowCount > 0 then return deferrals.done() else return deferrals.done('Access denied. Apply at discord.gg/yourinvite') end end)

    Admin QoL commands (example)

    RegisterCommand('wladd', function(src, args) if src ~= 0 then return end -- console only for simplicity local identifier = args[1] if not identifier or not identifier:find(':') then print('Usage: wladd identifierType:identifierValue') return end local ok = MySQL.prepare.await('INSERT IGNORE INTO whitelist (identifier,note,added_by) VALUES (?, ?, ?)', { > identifier, 'manual add', 'console' }) print(ok and ('Whitelisted: %s'):format(identifier) or 'Failed to add') end, true)

    RegisterCommand('wlrm', function(src, args) if src ~= 0 then return end local identifier = args[1] local ok = MySQL.prepare.await('DELETE FROM whitelist WHERE identifier = ?', { identifier }) print(ok and ('Removed: %s'):format(identifier) or 'Failed to remove') end, true)

    For mysql-async , replace MySQL.scalar.await with

    For mysql-async, replace MySQL.scalar.await with MySQL.Async.fetchScalar and the parameter style with @param/?. Prefer oxmysql for performance & await support.

    Performance

    • Keep a UNIQUE index on identifier (see schema).
    • Optionally warm a memory cache at startup and on change; hit DB only on cache miss.
    • Rate‑limit repeated failed connection attempts by license/IP.

    ---

    Multi‑Identifier Rules

    Some servers require multiple IDs (e.g., both Steam and Discord) for staff tiers. Example pattern:

    local function hasType(ids, typ) for id, _ in pairs(ids) do if id:sub(1, #typ+1) == (typ..':') then return true end end return false end

    -- Require license, and if staff, also discord if not hasType(ids, 'license') then return deferrals.done('Start the game normally (license missing).') end if staffModeEnabled and not hasType(ids, 'discord') then return deferrals.done('Join our Discord and link your account to enter.') end

    ---

    Using Discord as the Whitelist (no custom code)

    If your community runs on Discord, use txAdmin’s Discord Member or Discord Role modes:

    • Link txAdmin to your Discord guild.
    • Choose Discord Member to allow any guild member, or Discord Role to gate by a specific role (e.g., @Whitelisted).
    • Keep Approved License as a second gate if you want both conditions.

    Best practice: maintain a #whitelist-requests channel + lightweight form. Automate role assignment after approval via a bot or moderation flow.

    FAXES: A Discord Whitelist System for FiveM

    FAXES: A Discord Whitelist System for FiveM

    ---

    Integration Ideas

    • Discord bots: auto‑approve when a user completes an application, boosts, or subscribes.
    • Web panel: staff add/remove identifiers, with audit trail.
    • Paid tiers: grant discord role via your store (Tebex/Patreon) and let txAdmin role‑mode enforce access.

    ---

    Troubleshooting & Gotchas

    • Player not showing in txAdmin requests: Ensure whitelist is enabled in the correct profile; check that the player actually reached the deferral stage (watch txAdmin live console).
    • Steam ID missing: Steam must be running; don’t key your whitelist solely on steam:. Prefer license:.
    • Discord ID missing: User must have Discord running and your server must be set up to read discord:; verify Discord integration.
    • license vs license2: Some frameworks record two license fields; make sure your migration/DB queries consider both when moving data.
    • Deferral timeouts: Always call deferrals.update(...) while you await DB; respond within ~10–15 seconds.
    • Mismatched identifier format: Ensure you paste type:value exactly (lowercase type, colon separator).
    • High traffic spikes: Cache whitelist in memory, pre‑warm at start, and debounce DB calls.

    ---

    SEO FAQ (Schema‑ready content)

    What is the best identifier for FiveM whitelist?
    The Rockstar license: is the most universal and reliable; use it as your primary key.

    Can I whitelist with Discord without coding? Yes

    Can I whitelist with Discord without coding?
    Yes. txAdmin supports Discord Member and Discord Role whitelist modes once Discord is linked.

    Do I need Steam for whitelist?
    No. Many players don’t run Steam; avoid making steam: mandatory for baseline access.

    Can I combine multiple checks (e.g., license + Discord role)?
    Yes. Use txAdmin role mode and retain a license check in your custom script or admissions flow.

    How do I pre‑approve players?
    txAdmin → Whitelist → Add Approval, paste identifierType:identifier (e.g., license:...).

    ---

    Copy‑Paste Rejection Messages (use your brand)

    • Queue‑based: You’re not whitelisted yet. Apply in #whitelist-requests → discord.gg/yourinvite
    • Role‑gated: Your Discord account doesn’t have @Whitelisted. Join discord.gg/yourinvite and request access.
    • Maintenance: Server is in Admin‑only mode for maintenance. Please try again later.

    ---

    Conclusion

    A FiveM whitelist validates player identifiers during the connection deferral phase and blocks unapproved users before resources load. For most servers, enable Approved License in txAdmin, optionally layer Discord Role for community gating, and use a DB‑backed list with caching for scale.

    ---

    Appendix: Original Minimal Example (for reference)

    -- server.lua local whitelist = { > ["steam:110000132456789"] = true, ["license:abc123def456789"] = true, ["discord:123456789012345678"] = true }

    AddEventHandler("playerConnecting", function(name, setKickReason, deferrals) local player = source local identifiers = GetPlayerIdentifiers(player) local whitelisted = false

    deferrals.defer()

    for _, id in pairs(identifiers) do if whitelist[id] then whitelisted = true break end end

    if not whitelisted then deferrals.done("Not whitelisted. Apply at: your-discord.gg/invite") else deferrals.done() end end)