Skip to main content

​
Verification

The Verification module links a Discord account to a Minecraft player. Once linked, the player receives a Discord role and a LuckPerms group, their nickname is synced, and other modules (reports, whitelist, booster perks) can trust the identity behind the account.

​
Overview

Verification uses a one-time code exchange: a Discord user runs /verify, the bot DMs them a short code, and the player runs /verify <code> in-game to complete the link. Codes are generated with a cryptographically secure RNG and protected by expiry windows, attempt limits, and lockouts.

​
How Verification Works

The exchange happens across Discord and Minecraft in three steps:

​
Configuration

All keys live under features.verification in plugins/XDiscordUltimate/config.yml. 
features:
  verification:
    enabled: true
    one-time-only: true
    kick-after-minutes: 10
    whitelist-mode: false
    verified-role: "Verified"
    verified-group: "verified"
    sync-nickname: true
    code-length: 6
    code-expiry-minutes: 5
    verify-cooldown-seconds: 30
    failed-attempt-cooldown-seconds: 5
    max-verify-attempts: 5
    verify-lockout-seconds: 300

​
Key behavior

  • one-time-only — When true, a player only verifies once. Subsequent link attempts are rejected.
  • whitelist-mode — When true, only verified players can join the server. Unverified players are denied at login (combine with kick-after-minutes for a grace window).
  • kick-after-minutes — If a player joins but does not verify within this window, they are kicked.
  • verified-role — Discord role granted to the linked user (default Verified).
  • verified-group — LuckPerms group applied to the player in-game (default verified).
  • sync-nickname — When true, the player’s Discord nickname is set to their Minecraft username.
  • code-length — Number of characters in each code (default 6).
  • code-expiry-minutes — How long a code remains valid after it is DM’d (default 5).
  • verify-cooldown-seconds — Cooldown applied after a successful verification (default 30).
  • failed-attempt-cooldown-seconds — Cooldown added after each failed attempt (default 5).
  • max-verify-attempts — Failed attempts before lockout triggers (default 5).
  • verify-lockout-seconds — Lockout duration once the attempt cap is hit (default 300).

​
Commands

# Player, in-game — complete verification with the DM'd code
/verify <code>

# Player, in-game — remove your own link (v1.2.0+)
/unlink

# Admin — force-remove another player's link
/xdiscord unlink <player>
/unlink (and the admin equivalent) removes the Discord role, revokes the LuckPerms group, and deletes the database link in one operation.

​
Security

Codes are produced by java.security.SecureRandom, not a general-purpose Random. This makes code values effectively unguessable even if an attacker can observe output timing.
  • Expiry — Every code is invalidated after code-expiry-minutes (default 5 min). Expired codes cannot be reused.
  • Attempt throttling — Each failed /verify <code> adds a failed-attempt-cooldown-seconds (5s) cooldown before the next attempt is accepted.
  • Lockout — After max-verify-attempts (5) failures, the player is locked out for verify-lockout-seconds (300s). All further attempts during the lockout are rejected.
  • Per-player state — Codes are scoped to the requesting Discord user, so a leaked code is only useful to the player it was issued to.
Verification data persists across restarts in two database tables: verified_users (established links) and verification_codes (pending codes).

​
Next Steps

Support Tickets

Open private support channels from in-game with /support.

Permissions

Reference for every permission node, including xdiscord.bypass.filter.