Skip to content

User Manual v6.1.0

Jump to bottom
SzymeX edited this page Aug 23, 2026 · 1 revision

PureAuth 6.1.0 — Complete Wiki

PureAuth is an authentication plugin for Minecraft servers running Paper or Purpur. It provides password and PIN login, registration, sessions, CAPTCHA, 2FA, recovery questions, Premium Auto-Login, administrative tools, backend-switch synchronization, backups, Discord webhooks and optional PlaceholderAPI integration.

This manual covers every PureAuth 6.1.0 module:

  • Paper/Purpur backend
  • BungeeCord proxy
  • Velocity proxy

The Paper/Purpur module performs authentication and provides all player commands and GUI screens. The BungeeCord and Velocity modules synchronize an already authenticated player when they switch backend servers. A proxy jar does not replace the Paper jar.

Table of contents

  1. Requirements and compatibility
  2. Files and module selection
  3. Dependencies
  4. Installation
  5. Updating from 6.0.0
  6. Authentication flow
  7. PIN authentication
  8. Player commands
  9. Two-Factor Authentication
  10. Account recovery
  11. Administrative commands
  12. Permissions
  13. Paper/Purpur configuration
  14. BungeeCord configuration
  15. Velocity configuration
  16. Network synchronization
  17. PlaceholderAPI
  18. Recommended configurations
  19. Troubleshooting
  20. Security recommendations
  21. Quick reference

1. Requirements and compatibility

Paper/Purpur backend

Component PureAuth 6.1.0 requirement
Minecraft server line 26.2
API used by the plugin Paper API 26.2.build.36-alpha
api-version 26.2
Recommended server software Paper or Purpur compatible with the 26.2 API line
Java bytecode target Java 25
Effective backend Java requirement Java 25 for the supported Paper/Purpur 26.2 server line
server.properties online-mode=false

The backend module uses Paper-specific APIs. Spigot, Bukkit and Folia are not supported targets.

PureAuth checks the backend's online mode. Players are rejected by the fail-safe when the backend runs with online-mode=true, because PureAuth is designed to handle authentication itself.

BungeeCord proxy

Component PureAuth 6.1.0 requirement
Proxy API used to build the module BungeeCord API 1.21-R0.4
Java bytecode target Java 21
Recommended network Java Java 25, matching the backend runtime

Use a current BungeeCord-compatible proxy that supports the API line above. The Paper/Purpur servers behind it still follow the Paper requirements.

Velocity proxy

Component PureAuth 6.1.0 requirement
Proxy API used to build the module Velocity API 3.5.0-SNAPSHOT
Java bytecode target Java 21
Recommended network Java Java 25, matching the backend runtime

Use a current Velocity 3.5-compatible build. The Paper/Purpur servers behind it still follow the Paper requirements.

Online-mode layout

For a standalone backend:

online-mode=false

For a proxy network, the proxy is the public entry point and each backend running PureAuth must use:

online-mode=false

Protect backend ports so players cannot bypass the proxy. Configure BungeeCord or Velocity forwarding according to that proxy's official documentation.

2. Files and module selection

PureAuth 6.1.0 is distributed as three jars:

pureauth-paper-6.1.0-R.jar
pureauth-bungee-6.1.0-R.jar
pureauth-velocity-6.1.0-R.jar

Single Paper/Purpur server

Install only:

pureauth-paper-6.1.0-R.jar

BungeeCord network

Install:

pureauth-paper-6.1.0-R.jar       -> every authenticated Paper/Purpur backend
pureauth-bungee-6.1.0-R.jar      -> BungeeCord proxy

Velocity network

Install:

pureauth-paper-6.1.0-R.jar       -> every authenticated Paper/Purpur backend
pureauth-velocity-6.1.0-R.jar    -> Velocity proxy

Do not install both proxy jars on one proxy. Use the jar matching the proxy software.

3. Dependencies

PureAuth is standalone for its normal authentication functions. It does not require another Minecraft plugin to start or to provide password, PIN, 2FA, recovery, database or proxy synchronization features.

Optional dependency

PlaceholderAPI is optional and is used only for PureAuth placeholders:

%pureauth_logged%
%pureauth_has_2fa%

If PlaceholderAPI is absent, PureAuth continues to work and only the placeholders are unavailable.

Bundled runtime libraries

The release jars include or load the database, connection-pool and password-hashing libraries required by their module. Server owners do not install these as separate plugins.

External services

  • MySQL/MariaDB is required only when MYSQL is selected.
  • Mojang's profile API is contacted when a player enables Premium Auto-Login with /premium.
  • A Discord webhook is contacted only when Discord integration is enabled.
  • Redis fields are reserved for future synchronization and are not an active Redis implementation in 6.1.0.

4. Installation

4.1 Standalone Paper/Purpur

  1. Stop the server.
  2. Put pureauth-paper-6.1.0-R.jar in the server's plugins directory.
  3. Set online-mode=false in server.properties.
  4. Start the server once to generate plugins/PureAuth/config.yml.
  5. Stop the server and review the generated configuration.
  6. Start the server again.
  7. Confirm that the console reports PureAuth enabled without database errors.

SQLite is the simplest standalone choice:

database:
  type: "SQLITE"

4.2 BungeeCord network

  1. Stop the proxy and all backend servers.
  2. Put pureauth-bungee-6.1.0-R.jar in the BungeeCord plugins directory.
  3. Put pureauth-paper-6.1.0-R.jar in the plugins directory of every authenticated Paper/Purpur backend.
  4. Set every backend to online-mode=false.
  5. Start the proxy and backends once so both modules create their data directories.
  6. Configure all PureAuth instances to use the same MySQL/MariaDB database and table prefix.
  7. Keep network.mode: "LOCAL".
  8. Restart the entire network.
  9. Authenticate, switch to another backend and verify that authentication is synchronized.

4.3 Velocity network

  1. Stop the proxy and all backend servers.
  2. Put pureauth-velocity-6.1.0-R.jar in the Velocity plugins directory.
  3. Put pureauth-paper-6.1.0-R.jar in the plugins directory of every authenticated Paper/Purpur backend.
  4. Set every backend to online-mode=false.
  5. Configure Velocity forwarding and secure the backend ports.
  6. Start the proxy and backends once to generate configuration files.
  7. Configure all PureAuth instances to use the same MySQL/MariaDB database and table prefix.
  8. Keep network.mode: "LOCAL".
  9. Restart the entire network.
  10. Authenticate, switch to another backend and verify that authentication is synchronized.

SQLite must not be shared between separate servers. Use MySQL/MariaDB for a proxy network.

5. Updating from 6.0.0

  1. Stop every PureAuth server and proxy instance.
  2. Back up the existing database and all PureAuth configuration files.
  3. Replace each 6.0.0 jar with the corresponding 6.1.0 jar.
  4. Do not mix 6.0.0 and 6.1.0 modules on the same network.
  5. Start the Paper/Purpur backend so PureAuth can add the PIN database fields and new configuration defaults.
  6. Compare the generated 6.1.0 config with your customized config, especially settings.pin and the new PIN message keys.
  7. Start the proxy and remaining backends.
  8. Test password login, PIN setup/login, 2FA, recovery and a backend switch.

PureAuth stores PIN data in additional account columns. Existing password hashes remain intact, so existing accounts continue to use password login until a PIN is set.

Main changes in 6.1.0

  • Optional primary PIN authentication through a 54-slot GUI.
  • Configurable PIN length, defaulting to six digits.
  • Player-head number buttons for digits 0–9.
  • Two-entry PIN confirmation during setup.
  • PIN login automatically opens when a PIN-enabled player joins.
  • /login is blocked for PIN-enabled accounts while PIN support is active.
  • /changepass opens a PIN change flow for PIN-enabled accounts.
  • /rempin restores password login.
  • Recovery can remove a forgotten PIN while setting a new password.
  • Administrative setpin, changepin and rempin operations.
  • /pa alias for /pureauth.
  • Configurable PIN GUI items, textures, sounds, status text and notifications.

6. Authentication flow

Password account

Join -> registration or /login -> optional 2FA -> authenticated

PIN account

Join -> PIN GUI -> optional 2FA -> authenticated

PIN is the primary credential for a PIN-enabled account, but it does not replace 2FA. If 2FA is enabled, the player must complete it after the correct PIN.

Priority on join

For an account with an active PIN, PureAuth requires the PIN GUI before Premium Auto-Login or session restoration. This prevents a configured PIN from being bypassed by a session or IP-based Premium mode.

Protected player state

Before authentication, PureAuth blocks normal gameplay actions, including interaction, dropping items, taking damage, breaking/placing blocks and inventory manipulation. Chat is intercepted when it is used by an active 2FA or recovery flow.

Commands are restricted before login. Only the command required by the current authentication or recovery flow is accepted:

  • /register for an unregistered account without an active or halted PIN flow
  • /login for a password account without an active or halted PIN flow
  • /recovery ... when recovery is enabled
  • /2fa recovery <code> while waiting for 2FA login

Other commands are cancelled.

Failed attempts and account locking

Wrong PIN login attempts use the same strike and lock mechanism as wrong password attempts:

  • settings.max_attempts controls attempts before a kick.
  • settings.security.account_lock_enabled enables persistent locking.
  • settings.security.kicks_before_lock controls how many failed-attempt kicks occur before the account is locked.
  • /pureauth unlock <player> unlocks an account.

7. PIN authentication

PIN authentication is new in PureAuth 6.1.0.

7.1 Enabling a PIN as a player

The player must first log in normally, then run:

/setpin

The GUI opens and the player:

  1. Clicks the configured number heads to enter the new PIN.
  2. Enters the same PIN a second time.
  3. Receives confirmation after the PIN is securely saved.

By default, a PIN contains exactly six digits. The supported configured length range is 1–9. Invalid configured values safely fall back to six.

7.2 Logging in with a PIN

When a PIN-enabled player joins, the PIN window opens automatically. The entry is submitted automatically when the required number of digits has been clicked.

Available controls:

  • digit heads 0–9
  • backspace
  • clear
  • visual filled/empty input indicators
  • a status item showing the current flow stage

The entered digits are not sent as a chat command.

For PIN accounts, this command is blocked while PIN support is enabled:

/login <password>

7.3 Changing a PIN

A logged-in PIN user runs:

/changepass

No arguments are accepted for this PIN flow. The GUI asks for:

  1. Current PIN.
  2. New PIN.
  3. New PIN again for confirmation.

If the server owner changes the configured PIN length, an existing PIN is still verified using its stored length. The replacement PIN uses the current configured length.

7.4 Removing a PIN

A logged-in player runs:

/rempin

The PIN is removed and future logins use the account's existing password again.

7.5 Closing the login GUI

Closing the PIN login inventory with Escape or another inventory-closing action stops that login attempt. PureAuth:

  • marks the PIN login as halted;
  • stops normal login reminders;
  • displays a configurable title and chat message;
  • blocks /login, /register and unrelated commands for the rest of that connection;
  • tells the player to reconnect;
  • offers /recovery start only when recovery is enabled and configured for the account.

Closing a setup or change GUI cancels only that PIN operation.

7.6 PIN and recovery

If a player forgets a PIN and has configured recovery:

/recovery start

After answering the recovery question correctly:

/recovery pass <new_password> <new_password>

PureAuth atomically saves the new password and removes the forgotten PIN. Future logins use the new password. If the database operation fails, neither change is applied.

7.7 Disabling PIN globally

Set:

settings:
  pin:
    enabled: false

When disabled:

  • no PIN login GUI is required;
  • existing password hashes remain usable;
  • /login becomes the normal login method again;
  • /setpin and administrative PIN setting/changing are unavailable;
  • /rempin and administrative PIN removal can still remove stored PIN data.

8. Player commands

All player commands are provided by the Paper/Purpur module.

/register

Registers a new account.

/register <password> <password>
/register <password> <password> <captcha>   # when CAPTCHA is enabled

Requirements:

  • account is not already registered;
  • both passwords match;
  • password meets settings.min_password_length;
  • IP account limit is not exceeded;
  • CAPTCHA matches when enabled.

/login

Logs into a password account.

/login <password>

This command is blocked for a PIN-enabled account while settings.pin.enabled is true.

/changepass

For a password account:

/changepass <old_password> <new_password> <new_password>

For a PIN-enabled account:

/changepass

The PIN form requires the current PIN and the new PIN twice.

/setpin

/setpin

Enables PIN authentication through the GUI. The player must be logged in and must not already have a PIN.

/rempin

/rempin

Removes the player's PIN and restores password login. The player must be logged in.

/premium

/premium

Checks the player's name through Mojang's profile API and enables IP-trust Premium Auto-Login. The player must be logged in and settings.premium_login.enabled must be enabled.

The API connection and read timeouts are five seconds. Premium mode is not Mojang session authentication and does not require ProtocolLib.

/cracked

/cracked

Disables Premium Auto-Login for the logged-in player.

/2fa

/2fa setup
/2fa remove
/2fa recovery <backup_code>

See Two-Factor Authentication.

/recovery

/recovery setup
/recovery remove
/recovery start
/recovery pass <new_password> <new_password>

See Account recovery.

Player commands do not require explicit permission nodes.

9. Two-Factor Authentication

Setup

/2fa setup
  1. PureAuth generates a secret key.
  2. The player adds it to a compatible authenticator application.
  3. The player enters the current six-digit code in chat.
  4. PureAuth enables 2FA and generates backup codes.

The player must already be logged in and must not already have 2FA enabled.

Login sequence

For a password account:

password -> 2FA -> complete login

For a PIN account:

PIN GUI -> 2FA -> complete login

The PIN system does not disable, replace or bypass 2FA.

Removal

/2fa remove

The player enters a valid authenticator code in chat to confirm removal.

Backup-code recovery

/2fa recovery <backup_code>

This works when the player is logged in or is currently waiting for 2FA during login. A successful recovery disables 2FA and invalidates the previous backup-code set.

Admin Guard

When enabled, accounts with this permission must configure 2FA:

pureauth.admin.guard

Configuration:

settings:
  admin_guard:
    enabled: true

If an affected administrator removes 2FA, Admin Guard requires setup again on the next login.

10. Account recovery

Recovery must be enabled in the Paper config:

settings:
  recovery:
    enabled: true

Configure recovery

/recovery setup

The logged-in player chooses a configured question and enters an answer. The answer is hashed before storage.

Remove recovery

/recovery remove

The player must be logged in and have recovery configured.

Recover access

/recovery start

The unauthenticated player answers the configured question in chat. After successful verification:

/recovery pass <new_password> <new_password>

The recovery session expires, so the password command must be used within the active verified flow.

For an account using a PIN, successful password recovery also removes the forgotten PIN and restores password login.

Recovery question order matters. Accounts store the question ID. Reordering existing questions can make an older account display a different question.

11. Administrative commands

The administrative command and its alias are:

/pureauth
/pa

The alias supports all the same subcommands, for example /pa reload.

General and diagnostic commands

Command Description Permission Safe mode
/pureauth Shows plugin name and version none no
/pureauth reload Reloads config, backup scheduling and PIN GUI items pureauth.admin.reload no
/pureauth stats Shows user/config statistics; console only pureauth.admin.stats no
/pureauth info <player> Shows stored account information pureauth.admin.info no
/pureauth accounts <IP> Lists accounts registered from an IP pureauth.admin.accounts no
/pureauth location <login|register> Saves current player location as auth spawn pureauth.admin.location no

Sensitive account commands

Command Description Permission Safe mode
/pureauth unlock <player> Unlocks an account pureauth.admin.unlock yes
/pureauth unregister <player> Deletes the registered account pureauth.admin.unregister yes
/pureauth register <player> <password> Registers an account manually pureauth.admin.register yes
/pureauth forcelogin <player> Completes login for an online player pureauth.admin.forcelogin yes
/pureauth setpassword <player> <new_password> Replaces the stored password pureauth.admin.setpassword yes
/pureauth setpin <player> <pin> Enables PIN for an account that has none pureauth.admin.pin yes
/pureauth changepin <player> <pin> Replaces an existing PIN pureauth.admin.pin yes
/pureauth rempin <player> Removes an existing PIN pureauth.admin.pin yes

When settings.safe_mode: true, sensitive commands can be run only from the console.

Administrative PIN values must contain exactly the configured number of digits. setpin refuses an account that already has a PIN; use changepin. changepin and rempin require an existing PIN.

If an administrator changes PIN state for an online player:

  • an authenticated player receives a notice that the change applies on the next login;
  • an unauthenticated player is disconnected and told to rejoin safely.

Passwords and PINs are redacted from PureAuth's administrative command audit log.

12. Permissions

pureauth.admin
pureauth.admin.reload
pureauth.admin.stats
pureauth.admin.unlock
pureauth.admin.unregister
pureauth.admin.register
pureauth.admin.forcelogin
pureauth.admin.info
pureauth.admin.setpassword
pureauth.admin.accounts
pureauth.admin.location
pureauth.admin.pin
pureauth.admin.guard

pureauth.admin is declared as the general administrator permission, but command handling checks the specific sub-permission for each operation. Assign the specific nodes or configure parent/child inheritance in your permissions plugin.

pureauth.admin.guard is different from command access. It marks an account as requiring 2FA when Admin Guard is enabled, and defaults to false.

13. Paper/Purpur configuration

File:

plugins/PureAuth/config.yml

13.1 Database

database:
  type: "SQLITE" # SQLITE or MYSQL
  pool:
    maximum_pool_size: -1
    minimum_idle: -1
    connection_timeout_ms: 10000
    idle_timeout_ms: 600000
    max_lifetime_ms: 1800000
  mysql:
    host: "localhost"
    port: 3306
    database: "minecraft"
    username: "root"
    password: "password"
    table_prefix: "pureauth_"
  • SQLITE stores data locally in plugins/PureAuth/database.db.
  • MYSQL uses MySQL/MariaDB and is recommended for production networks.
  • Default pool sizing with -1: SQLite uses one connection; MySQL uses up to 16 with up to four idle.
  • Keep SQLite's maximum pool size at one.
  • connection_timeout_ms is how long a task waits for a connection.
  • idle_timeout_ms retires unused connections.
  • max_lifetime_ms prevents stale long-lived connections.
  • table_prefix may contain letters, numbers and underscores.

Use a dedicated database user instead of MySQL root in production.

13.2 Async performance

performance:
  async:
    database_threads: 8
    crypto_threads: 4
    network_threads: 4
    queue_size: 512

Database, BCrypt and external-network work runs through bounded worker queues to avoid blocking the main server thread.

  • database_threads: account/database operations.
  • crypto_threads: password, PIN, answer and backup-code hashing/checking.
  • network_threads: Mojang API and other network work.
  • queue_size: upper bound for queued tasks per worker group.

Do not configure many more database workers than the database pool can serve. Do not make crypto_threads excessively high; BCrypt is intentionally CPU-intensive.

13.3 Network mode

network:
  mode: "LOCAL"
  redis:
    host: "localhost"
    port: 6379
    password: ""
    database: 0
    channel: "pureauth:network"

Use LOCAL in PureAuth 6.1.0. REDIS and its connection fields are reserved for future multi-proxy shared state and do not provide complete Redis synchronization in this release.

13.4 General settings

settings:
  safe_mode: false
  language: "EN"
  blindness_effect: true
  • safe_mode: makes sensitive admin commands console-only.
  • language: EN or PL.
  • blindness_effect: adds blindness while the player is in unauthenticated ghost mode.

13.5 PIN settings

settings:
  pin:
    enabled: true
    length: 6
    gui:
      title: "&#54DAF4&lPureAuth &8| &dPIN"
      digit_material: "PLAYER_HEAD"
      filler:
        material: "GRAY_STAINED_GLASS_PANE"
        name: " "
      input:
        filled:
          material: "LIME_STAINED_GLASS_PANE"
          name: "&a&l●"
        empty:
          material: "BLACK_STAINED_GLASS_PANE"
          name: "&8○"
      status_material: "NETHER_STAR"

Status labels

status:
  login: "&b&lENTER PIN"
  setup_new: "&a&lSET A NEW PIN"
  setup_confirm: "&e&lCONFIRM YOUR PIN"
  change_current: "&6&lENTER CURRENT PIN"
  change_new: "&a&lENTER NEW PIN"
  change_confirm: "&e&lCONFIRM NEW PIN"
  complete: "&a&lCOMPLETE"
status_lore:
  - "&7Click the number heads below."
  - "&7The entry submits automatically."

Controls

controls:
  backspace:
    material: "ARROW"
    name: "&e&lBACKSPACE"
    lore: ["&7Remove the last digit."]
    texture: ""
  clear:
    material: "BARRIER"
    name: "&c&lCLEAR"
    lore: ["&7Clear all entered digits."]
    texture: ""

Digit heads

Each digit from "0" through "9" accepts its own Base64 texture, display name and lore:

digits:
  "0":
    texture: "<Base64 texture value>"
    name: "&b&l0"
    lore: ["&7Click to enter 0."]

The default config already contains textures for all ten number heads. If a material or texture is invalid, PureAuth uses safe item fallbacks rather than crashing the plugin.

Sounds

sounds:
  enabled: true
  open: "minecraft:block.ender_chest.open"
  click: "minecraft:ui.button.click"
  step: "minecraft:block.note_block.pling"
  success: "minecraft:entity.player.levelup"
  error: "minecraft:entity.villager.no"

Use namespaced sound keys supported by the installed Paper/Purpur version. Set enabled: false to disable all PIN GUI sounds.

Run /pureauth reload after editing GUI options. Reload rebuilds cached PIN GUI items for future windows.

13.6 Premium Auto-Login

settings:
  premium_login:
    enabled: true
    require_same_ip: true

Keeping require_same_ip: true is safer. A PIN-enabled account still requires its PIN before this feature can complete authentication.

13.7 Backup system

settings:
  backup:
    enabled: true
    interval_hours: 24
    max_backups: 10

PureAuth backs up the SQLite database or exports MySQL data according to the selected database mode. Older files beyond max_backups are removed.

13.8 Recovery questions

settings:
  recovery:
    enabled: true
    questions:
      - "What is your mother's maiden name?"
      - "What was the name of your first pet?"
      - "What is your favorite color?"

Questions may be translated, but avoid changing their order after players have configured recovery.

13.9 Discord webhooks

settings:
  discord:
    enabled: false
    webhook_url: "YOUR_WEBHOOK_HERE"
    events:
      server_lifecycle: true
      user_login: false
      user_register: true
      user_changepass: true
      user_premium_toggle: true
      failed_attempts: true
      account_locked: true
      admin_usage: true
      admin_sensitive: true

PIN updates use the change-password event category for player activity and the sensitive-admin category for administrative PIN changes.

13.10 Account lock and limits

settings:
  security:
    account_lock_enabled: true
    kicks_before_lock: 3
  captcha:
    enabled: true
    length: 5
    characters: "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
  login_timeout: 60
  max_attempts: 3
  min_password_length: 4
  max_accounts_per_ip: 3
  • login_timeout: seconds available for registration/login.
  • max_attempts: wrong password or PIN attempts before kick.
  • kicks_before_lock: failed-attempt kicks before persistent account locking.
  • min_password_length: minimum registration/change/recovery password length.
  • max_accounts_per_ip: registration limit per IP.

13.11 Sessions

settings:
  sessions:
    enabled: true
    time_minutes: 1

Sessions allow a recent password account to reconnect without entering the password. Active PIN accounts require the PIN GUI and do not bypass it through a stored session.

13.12 Admin Guard, updater and reminders

settings:
  admin_guard:
    enabled: true
  update_checker: true
  message_interval: 10

message_interval is the number of seconds between login/register reminder messages.

13.13 Login and registration locations

settings:
  locations:
    spawn_login: ""
    spawn_register: ""

Set locations in game instead of editing the serialized values:

/pureauth location login
/pureauth location register

13.14 Messages and language

Messages are stored under:

messages:
  en:
    ...
  pl:
    ...

Select a section with:

settings:
  language: "EN" # EN or PL

All PIN notifications, halted-login titles and recovery hints are configurable. PIN-specific keys include:

pin_login_open
pin_login_reminder
pin_setup_open
pin_change_open
pin_confirm_prompt
pin_mismatch
pin_current_success
pin_current_wrong
pin_login_success
pin_saved
pin_removed
pin_not_set
pin_already_set
pin_disabled
pin_invalid
pin_database_error
pin_gui_cancelled
pin_command_no_args
pin_login_command_blocked
pin_changepass_gui_only
pin_admin_changed_notice
pin_admin_rejoin
pin_halted_title
pin_halted_subtitle
pin_halted_subtitle_recovery
pin_halted_chat
pin_halted_chat_recovery
recovery_pin_removed
admin_pin_set
admin_pin_changed
admin_pin_removed
admin_pin_already_set
admin_pin_not_set
admin_usage_setpin
admin_usage_changepin
admin_usage_rempin

Useful placeholders inside messages include %length%, %player%, %attempts%, %max%, %time%, %code%, %question%, %current% and %new%, depending on the key.

14. BungeeCord configuration

File:

plugins/PureAuth/config.yml

Default structure:

database:
  type: MYSQL
  pool:
    maximum_pool_size: 16
    minimum_idle: 4
    connection_timeout_ms: 10000
    idle_timeout_ms: 600000
    max_lifetime_ms: 1800000
  mysql:
    host: "localhost"
    port: 3306
    database: "pureauth"
    username: "root"
    password: ""
    table_prefix: "pureauth_"

settings:
  language: "EN"

network:
  mode: "LOCAL"
  redis:
    host: "localhost"
    port: 6379
    password: ""
    database: 0
    channel: "pureauth:network"

Use the same MySQL database credentials and table_prefix as the Paper backends. Keep LOCAL in 6.1.0.

The BungeeCord module registers the pureauth:sync plugin-message channel, remembers authenticated UUIDs while connected, forwards authentication success on a backend switch and removes session state when the player disconnects.

It does not display the PIN GUI and does not register /login, /setpin or the other Paper commands.

15. Velocity configuration

File:

plugins/pureauth/config.yml

Default structure:

database:
  driver: "MYSQL"
  pool:
    maximum_pool_size: 16
    minimum_idle: 4
    connection_timeout_ms: 10000
    idle_timeout_ms: 600000
    max_lifetime_ms: 1800000
  host: "localhost"
  port: "3306"
  database: "pureauth"
  username: "root"
  password: ""
  prefix: "pureauth_"

network:
  mode: "LOCAL"
  redis:
    host: "localhost"
    port: 6379
    password: ""
    database: 0
    channel: "pureauth:network"

Velocity uses database.driver and database.prefix, while the Paper and Bungee configs use database.type and database.mysql.table_prefix. Point every module at the same database and equivalent prefix.

The Velocity module registers pureauth:sync, remembers authenticated UUIDs while connected, sends authentication success after a backend switch and clears session state on disconnect.

It does not display the PIN GUI and does not register /login, /setpin or the other Paper commands.

16. Network synchronization

The Paper module sends this internal event to the proxy after authentication:

PLAYER_LOGIN:<uuid>

When the same player switches backend, the proxy sends:

AUTH_SUCCESS:<uuid>

The receiving Paper backend completes the synchronized authentication flow.

Requirements for reliable synchronization

  • matching PureAuth 6.1.0 modules;
  • Paper module on every protected backend;
  • exactly one appropriate proxy module;
  • the pureauth:sync plugin-message channel must not be blocked;
  • shared UUID identity through correct proxy forwarding;
  • shared MySQL/MariaDB account storage and matching table prefix;
  • backend ports protected from direct connections.

Scope of LOCAL mode

Authenticated UUIDs are held in the proxy module's memory for the active connection. They are removed on disconnect. LOCAL is appropriate for one proxy instance. Complete multi-proxy Redis session state is not implemented in 6.1.0.

17. PlaceholderAPI

PlaceholderAPI is a soft dependency of the Paper module.

%pureauth_logged%

Returns:

true
false

Shows whether the player is currently authenticated on that Paper server.

%pureauth_has_2fa%

Returns:

true
false

Shows the cached 2FA-enabled state. The cache avoids a database query during every placeholder request.

18. Recommended configurations

Small standalone server

database:
  type: "SQLITE"
  pool:
    maximum_pool_size: 1
    minimum_idle: 1

performance:
  async:
    database_threads: 2
    crypto_threads: 2
    network_threads: 2
    queue_size: 128

network:
  mode: "LOCAL"

settings:
  pin:
    enabled: true
    length: 6

Medium MySQL server

database:
  type: "MYSQL"
  pool:
    maximum_pool_size: 16
    minimum_idle: 4

performance:
  async:
    database_threads: 4
    crypto_threads: 4
    network_threads: 4
    queue_size: 256

network:
  mode: "LOCAL"

Proxy network

Paper backends:

database:
  type: "MYSQL"
  pool:
    maximum_pool_size: 16
    minimum_idle: 4
    connection_timeout_ms: 10000
    idle_timeout_ms: 600000
    max_lifetime_ms: 1800000

performance:
  async:
    database_threads: 8
    crypto_threads: 4
    network_threads: 4
    queue_size: 512

network:
  mode: "LOCAL"

Configure the matching proxy module with the same MySQL server, database and table prefix.

Tune pools only after measuring load. Setting very large pool, thread or queue values can increase database and CPU pressure instead of improving login performance.

19. Troubleshooting

Players are rejected because online mode must be false

Set on every Paper/Purpur backend:

online-mode=false

Then restart the backend. Do not expose its port publicly.

PIN GUI does not open

Check:

settings:
  pin:
    enabled: true

Confirm the account actually has a PIN and the Paper module is 6.1.0. The proxy module alone cannot open a GUI.

/login is blocked

This is expected for an account with a PIN while PIN support is enabled. Use the automatically opened PIN GUI. If it was closed during login, reconnect. If configured for that account, use /recovery start.

PIN is rejected after changing settings.pin.length

Existing PINs store their own length and should continue to use that length. New or changed PINs use the currently configured length. Administrative commands must use the current configured length.

PIN GUI was closed and no commands work

The login was deliberately halted for that connection. Reconnect. Recovery remains available only if it is enabled and the account has configured a question.

Password recovery removed the PIN

This is intended. Recovery sets a new password and removes the forgotten PIN so the account cannot remain locked behind an unknown primary credential.

Player is asked for 2FA after the correct PIN

This is intended. PIN is the primary credential; 2FA is the second factor.

/register <password> <password> shows usage

CAPTCHA may be enabled. Use:

/register <password> <password> <captcha>

SQLite fails in a network

Do not share SQLite across proxy/backends. Configure MySQL/MariaDB on all modules.

Backend switching asks for login again

Check all of the following:

  • correct BungeeCord or Velocity jar is running on the proxy;
  • Paper 6.1.0 runs on both source and destination backend;
  • plugin-message forwarding is working;
  • UUID forwarding is consistent;
  • player did not disconnect from the proxy between switches;
  • database credentials and table prefix match.

Velocity cannot load database settings

Velocity's keys differ from Paper/Bungee. Use driver, flat host/port fields and prefix exactly as shown in the Velocity section.

Premium Auto-Login does not work

Check settings.premium_login.enabled, the saved IP requirement and access to Mojang's profile API. PIN-enabled accounts intentionally require their PIN first.

Placeholders are unchanged or unknown

Install a compatible PlaceholderAPI build on the Paper/Purpur backend. PureAuth itself does not require it for authentication.

Admin command says no permission

Assign the exact sub-permission. pureauth.admin alone is not automatically treated by command code as every specific permission unless your permissions system provides inheritance.

PIN items or sounds are invalid

Use valid Paper material names, valid Base64 head textures and namespaced sound keys. Run /pureauth reload. PureAuth uses safe GUI item fallbacks for invalid material/texture configuration.

Database is unavailable

Check host, port, credentials, database name, table prefix, firewall and pool timeout. PureAuth reports save failure instead of treating an unsuccessful PIN/recovery write as successful.

20. Security recommendations

  • Keep Paper/Purpur backends in online-mode=false, but firewall them so only the proxy can connect.
  • Use a dedicated MySQL/MariaDB user with access only to the PureAuth database.
  • Use strong player passwords even if PIN login is enabled; the password is the safe fallback when PIN is disabled or removed.
  • Keep the default six-digit PIN or increase it within the supported 1–9 range when appropriate.
  • Enable 2FA for administrators and assign pureauth.admin.guard to staff accounts.
  • Enable safe mode so sensitive administrative changes are console-only.
  • Keep account locking and failed-attempt limits enabled.
  • Encourage players to configure recovery before they need it.
  • Keep recovery answers private and difficult to guess.
  • Save 2FA backup codes outside Minecraft.
  • Keep Premium Auto-Login's same-IP requirement enabled.
  • Never publish database passwords, webhook URLs or complete config files containing secrets.
  • Back up the database before updates and test restoration periodically.

21. Quick reference

Player commands

/register <password> <password> [captcha]
/login <password>
/changepass <old> <new> <new>   # password account
/changepass                     # PIN account
/setpin
/rempin
/premium
/cracked
/2fa setup
/2fa remove
/2fa recovery <code>
/recovery setup
/recovery remove
/recovery start
/recovery pass <new> <new>

Admin commands

/pureauth
/pa
/pureauth reload
/pureauth stats
/pureauth unlock <player>
/pureauth unregister <player>
/pureauth register <player> <password>
/pureauth forcelogin <player>
/pureauth info <player>
/pureauth setpassword <player> <new_password>
/pureauth setpin <player> <pin>
/pureauth changepin <player> <pin>
/pureauth rempin <player>
/pureauth accounts <IP>
/pureauth location <login|register>

Module placement

Standalone: Paper jar on Paper/Purpur
Bungee:    Paper jar on every backend + Bungee jar on proxy
Velocity:  Paper jar on every backend + Velocity jar on proxy

Essential production settings

Backend online-mode=false
Protected backend ports
Shared MySQL for networks
network.mode=LOCAL
Matching PureAuth 6.1.0 modules

PureAuth 6.1.0 is developed by SzymeX Dev Studio.

Clone this wiki locally