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

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. 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 = 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 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 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 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

---

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. 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 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)