Skip to content

User Manual v6.0.0

Jump to bottom
SzymeX edited this page Jul 6, 2026 · 2 revisions 
# PureAuth 6.0.0 - User Manual

PureAuth is an advanced authentication plugin for Minecraft servers running on Paper/Purpur.  
It provides registration, login, sessions, CAPTCHA, 2FA, recovery questions, Premium Auto-Login, admin tools, proxy sync, backups, Discord webhooks and PlaceholderAPI support.

---

## 1. Requirements

### Server software

PureAuth Paper module requires:

- Paper-compatible server
- Recommended: Paper or Purpur
- Not supported:
  - Spigot
  - Bukkit
  - Folia

Why not Spigot?  
PureAuth uses Paper-specific API, including Paper chat events. Because of that, the backend jar is named:

```text
pureauth-paper-6.0.0.jar

Java version

PureAuth 6.0.0 requires:

Java 25

The plugin is compiled for Java 21 but it requires Java 25 to be installed!

Minecraft / API

PureAuth Paper uses:

api-version: '26.2'

Use a Paper/Purpur version compatible with this API line.

Server online-mode

Your backend Paper server must have:

online-mode=false

PureAuth has a fail-safe check. If online-mode=true, the plugin will disable itself.

This is required because PureAuth handles authentication itself.

2. Plugin files

PureAuth 6.0.0 produces three main jars:

pureauth-paper-6.0.0.jar
pureauth-bungee-6.0.0.jar
pureauth-velocity-6.0.0.jar

Which jar should I use?

Single Paper/Purpur server

Use only:

pureauth-paper-6.0.0.jar

Network with BungeeCord

Use:

pureauth-paper-6.0.0.jar
pureauth-bungee-6.0.0.jar

Put pureauth-paper on backend Paper servers.
Put pureauth-bungee on the BungeeCord proxy.

Network with Velocity

Use:

pureauth-paper-6.0.0.jar
pureauth-velocity-6.0.0.jar

Put pureauth-paper on backend Paper servers.
Put pureauth-velocity on the Velocity proxy.

3. Installation

Basic installation

  1. Stop your server.
  2. Put pureauth-paper-6.0.0.jar into the plugins folder.
  3. Make sure server.properties contains:
online-mode=false
  1. Start the server.
  2. Edit the generated config.
  3. Restart the server after changing important database settings.

Recommended database setup

For a small standalone server:

database:
  type: "SQLITE"

For a larger server or network:

database:
  type: "MYSQL"

For networks, MySQL/MariaDB is strongly recommended.

4. Main features

PureAuth includes:

  • Player registration
  • Player login
  • Password changing
  • CAPTCHA
  • Login timeout
  • Maximum login attempts
  • Account locking
  • Sessions
  • Premium Auto-Login
  • Cracked mode toggle
  • Two-Factor Authentication
  • 2FA backup codes
  • Recovery questions
  • Admin Guard
  • Ghost mode before login
  • Login/register spawn locations
  • Discord webhooks
  • Automatic backups
  • PlaceholderAPI support
  • BungeeCord and Velocity sync
  • SQLite and MySQL/MariaDB support

5. Player commands

/register

Registers a new account.

Usage without CAPTCHA:

/register <password> <password>

Usage with CAPTCHA enabled:

/register <password> <password> <captcha>

Example:

/register mySecret123 mySecret123 A8K2P

Requirements:

  • Player must not already be logged in.
  • Player must not already be registered.
  • Passwords must match.
  • Password must meet settings.min_password_length.
  • IP must not exceed settings.max_accounts_per_ip.
  • If CAPTCHA is enabled, the correct CAPTCHA code must be provided.

Permission:

None

/login

Logs into an existing account.

Usage:

/login <password>

Example:

/login mySecret123

Requirements:

  • Player must be registered.
  • Account must not be locked.
  • Password must be correct.
  • If 2FA is enabled, the player must also complete 2FA.

Permission:

None

/changepass

Changes the player's password.

Usage:

/changepass <old_password> <new_password> <new_password>

Example:

/changepass oldPass123 newPass456 newPass456

Requirements:

  • Player must be logged in.
  • Old password must be correct.
  • New passwords must match.
  • New password must meet minimum length.

Permission:

None

/premium

Enables Premium Auto-Login for the player.

Usage:

/premium

What it does:

  • Checks the player's Minecraft username using Mojang API.
  • If the name belongs to a premium account, Premium mode is enabled.
  • Future logins can be automatic if the IP matches, depending on config.

Requirements:

  • Player must be logged in.
  • settings.premium_login.enabled must be true.

Permission:

None

Important:

Premium Auto-Login in PureAuth is IP-trust based. It does not replace Mojang authentication and does not require ProtocolLib.

/cracked

Disables Premium Auto-Login for the player.

Usage:

/cracked

Requirements:

  • Player must be logged in.
  • Player must currently have Premium mode enabled.

Permission:

None

6. Two-Factor Authentication commands

Main command:

/2fa <setup|remove|recovery>

/2fa setup

Starts 2FA setup.

Usage:

/2fa setup

What happens:

  1. PureAuth generates a secret key.
  2. Player adds the key to an authenticator app.
  3. Player types the 6-digit code in chat.
  4. If the code is correct, 2FA is enabled.
  5. Backup codes are generated.

Requirements:

  • Player must be logged in.
  • Player must not already have 2FA enabled.

Permission:

None

/2fa remove

Starts 2FA removal.

Usage:

/2fa remove

What happens:

  1. Player is asked to enter a 2FA code in chat.
  2. If the code is correct, 2FA is disabled.

Requirements:

  • Player must be logged in.
  • Player must have 2FA enabled.

Permission:

None

/2fa recovery

Uses a 2FA backup code to disable 2FA.

Usage:

/2fa recovery <backup_code>

Example:

/2fa recovery A1B2C3D4

Requirements:

  • Player must be logged in or currently waiting for 2FA during login.
  • Backup code must be valid.

Permission:

None

Important:

After successful recovery, previous backup codes become invalid.

7. Recovery commands

Main command:

/recovery <setup|remove|start|pass>

Recovery system must be enabled:

settings:
  recovery:
    enabled: true

/recovery setup

Sets up a recovery question.

Usage:

/recovery setup

What happens:

  1. Player selects one of the configured questions.
  2. Player types an answer.
  3. Answer is hashed and saved.

Requirements:

  • Player must be logged in.
  • Recovery must not already be configured.

Permission:

None

/recovery remove

Removes recovery questions from the account.

Usage:

/recovery remove

Requirements:

  • Player must be logged in.
  • Recovery must already be configured.

Permission:

None

/recovery start

Starts account recovery.

Usage:

/recovery start

What happens:

  1. Player is asked their configured recovery question.
  2. Player types the answer in chat.
  3. If correct, they can set a new password using /recovery pass.

Requirements:

  • Player must not be logged in.
  • Recovery must be configured.

Permission:

None

/recovery pass

Sets a new password after successful recovery verification.

Usage:

/recovery pass <new_password> <new_password>

Example:

/recovery pass newPass123 newPass123

Requirements:

  • Player must have completed /recovery start.
  • Recovery answer must be verified.
  • Passwords must match.
  • Password must meet minimum length.

Permission:

None

8. Admin commands

Main admin command:

/pureauth

Running /pureauth with no arguments displays basic plugin information.

Important:

Although pureauth.admin exists, the current command checks specific permissions for each subcommand.
If you use a permissions plugin, give admins the specific permissions listed below or configure inheritance yourself.

/pureauth reload

Reloads the config and restarts the backup task.

Usage:

/pureauth reload

Permission:

pureauth.admin.reload

/pureauth stats

Shows plugin statistics.

Usage:

/pureauth stats

Permission:

pureauth.admin.stats

Important:

This command is console-only.

/pureauth unlock

Unlocks a locked account.

Usage:

/pureauth unlock <player>

Example:

/pureauth unlock Steve

Permission:

pureauth.admin.unlock

Affected by safe mode:

settings:
  safe_mode: true

If safe mode is enabled, this command can only be used from console.

/pureauth unregister

Deletes a player's registered account.

Usage:

/pureauth unregister <player>

Example:

/pureauth unregister Steve

Permission:

pureauth.admin.unregister

Affected by safe mode:

settings:
  safe_mode: true

If safe mode is enabled, this command can only be used from console.

/pureauth register

Manually registers an account for a player.

Usage:

/pureauth register <player> <password>

Example:

/pureauth register Steve strongPassword123

Permission:

pureauth.admin.register

Affected by safe mode:

settings:
  safe_mode: true

If safe mode is enabled, this command can only be used from console.

/pureauth forcelogin

Forcefully logs in an online player.

Usage:

/pureauth forcelogin <player>

Example:

/pureauth forcelogin Steve

Permission:

pureauth.admin.forcelogin

Affected by safe mode:

settings:
  safe_mode: true

If safe mode is enabled, this command can only be used from console.

/pureauth info

Shows account information for a player.

Usage:

/pureauth info <player>

Example:

/pureauth info Steve

Permission:

pureauth.admin.info

Shows information such as:

  • UUID
  • IP
  • Last login
  • Registration date
  • Premium mode
  • Locked status
  • Recovery status
  • 2FA status

/pureauth setpassword

Sets a new password for a player.

Usage:

/pureauth setpassword <player> <new_password>

Example:

/pureauth setpassword Steve newPassword123

Permission:

pureauth.admin.setpassword

Affected by safe mode:

settings:
  safe_mode: true

If safe mode is enabled, this command can only be used from console.

/pureauth accounts

Shows accounts registered from an IP address.

Usage:

/pureauth accounts <IP>

Example:

/pureauth accounts 127.0.0.1

Permission:

pureauth.admin.accounts

/pureauth location

Sets login or register spawn location.

Usage:

/pureauth location <login|register>

Examples:

/pureauth location login
/pureauth location register

Permission:

pureauth.admin.location

Requirements:

  • Sender must be a player.
  • Player's current location is saved.

9. Permissions list

General admin permission

pureauth.admin

Description:

General admin permission defined in plugin.yml.

Important:

Current command logic checks specific sub-permissions.
Recommended: assign the permissions below directly.

Admin command permissions

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

Admin Guard permission

pureauth.admin.guard

Default:

false

What it does:

Players with this permission are forced to enable 2FA if Admin Guard is enabled.

Config:

settings:
  admin_guard:
    enabled: true

If a player with pureauth.admin.guard logs in without 2FA, PureAuth will force them into 2FA setup.

10. PlaceholderAPI

PureAuth supports PlaceholderAPI if PlaceholderAPI is installed.

Soft dependency:

softdepend: [PlaceholderAPI]

Available placeholders:

%pureauth_logged%

Returns:

true
false

Description:

Shows whether the player is currently logged in.

%pureauth_has_2fa%

Returns:

true
false

Description:

Shows whether the player has 2FA enabled according to PureAuth cache.

Important:

This placeholder uses cached data for performance. It is designed to avoid direct database queries from PlaceholderAPI calls.

11. Config explanation

Main config file:

plugins/PureAuth/config.yml

Database configuration

database:
  type: "SQLITE" # Options: SQLITE, 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_"

This section controls where PureAuth stores accounts, passwords, 2FA data, sessions data, recovery data and account information.

database.type

type: "SQLITE"

Available options:

SQLITE
MYSQL

SQLITE

Uses a local database file:

plugins/PureAuth/database.db

Good for:

  • small servers
  • testing
  • simple standalone setups

Not recommended for:

  • large networks
  • multiple backend servers
  • multiple proxy instances

MYSQL

Uses MySQL or MariaDB.

Recommended for:

  • production servers
  • networks
  • many players
  • multiple backend servers
  • BungeeCord/Velocity setups

database.pool

The pool controls how many database connections PureAuth can keep open and reuse.

A connection pool is like a queue of ready database connections.
Instead of opening a new database connection every time a player logs in, PureAuth reuses existing ones.

This improves performance, especially when many players log in at once.

maximum_pool_size

maximum_pool_size: -1

Controls the maximum number of database connections.

-1 means:

Use PureAuth default

PureAuth defaults:

SQLite: 1
MySQL/MariaDB: 16

Recommended values:

SQLite

maximum_pool_size: 1

SQLite works best with one database writer.
Do not set this high for SQLite.

MySQL / MariaDB - small server

maximum_pool_size: 8

MySQL / MariaDB - medium server

maximum_pool_size: 16

MySQL / MariaDB - large network

maximum_pool_size: 16-32

Do not randomly set this to 100.
More connections are not always better. Too many connections can overload MySQL.

minimum_idle

minimum_idle: -1

Controls how many database connections should stay ready even when the server is calm.

-1 means:

Use PureAuth default

PureAuth default:

SQLite: 1
MySQL/MariaDB: up to 4

Recommended values:

SQLite

minimum_idle: 1

MySQL / MariaDB

minimum_idle: 4

For very large networks:

minimum_idle: 8

connection_timeout_ms

connection_timeout_ms: 10000

How long PureAuth waits for a database connection before failing.

Value is in milliseconds.

10000 ms = 10 seconds

Recommended:

connection_timeout_ms: 10000

If your database is remote or sometimes slow:

connection_timeout_ms: 15000

If this timeout is reached, it usually means:

  • database is offline,
  • database is overloaded,
  • pool is too small,
  • network connection to database is slow,
  • too many login operations are happening at once.

idle_timeout_ms

idle_timeout_ms: 600000

How long an unused database connection can stay open before the pool closes it.

Value is in milliseconds.

600000 ms = 10 minutes

Recommended:

idle_timeout_ms: 600000

Usually you do not need to change this.

max_lifetime_ms

max_lifetime_ms: 1800000

Maximum lifetime of a database connection.

Value is in milliseconds.

1800000 ms = 30 minutes

Recommended:

max_lifetime_ms: 1800000

This helps prevent old/stale MySQL connections from staying open forever.

database.mysql

This section is used only when:

database:
  type: "MYSQL"

host

host: "localhost"

Database host.

Examples:

host: "localhost"
host: "127.0.0.1"
host: "mysql.example.com"

port

port: 3306

MySQL/MariaDB port.

Default:

3306

database

database: "minecraft"

Name of the MySQL/MariaDB database.

Example:

database: "pureauth"

username

username: "root"

Database username.

Recommended:

Do not use root in production.
Create a separate database user for PureAuth.

password

password: "password"

Database password.

Use a strong password.

table_prefix

table_prefix: "pureauth_"

Prefix added before PureAuth table names.

Default table:

pureauth_users

Useful when multiple plugins or multiple PureAuth instances share one database.

Allowed characters:

letters, numbers, underscores

Example:

table_prefix: "lobby_auth_"

Performance configuration

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

This section controls PureAuth internal async workers.

PureAuth does heavy operations outside the main server thread, for example:

  • database reads/writes,
  • BCrypt password hashing,
  • Mojang API checks,
  • network-related tasks.

This helps avoid lag when many players log in at the same time.

database_threads

database_threads: 8

How many worker threads can process database tasks.

Examples of database tasks:

  • checking if player is registered,
  • loading account snapshot,
  • updating login IP,
  • saving 2FA status,
  • saving recovery data,
  • saving logout location.

Recommended:

Small server

database_threads: 2

Medium server

database_threads: 4

Large server/network

database_threads: 8

Important:

This should make sense with your database pool.

Example:

database_threads: 8
database:
  pool:
    maximum_pool_size: 16

That is reasonable.

Bad example:

database_threads: 32
database:
  pool:
    maximum_pool_size: 4

That creates too many database tasks waiting for too few connections.

crypto_threads

crypto_threads: 4

How many worker threads can process password hashing/checking.

PureAuth uses BCrypt, which is intentionally CPU-heavy.
This is good for security, but it must be controlled.

Used for:

  • checking /login password,
  • hashing /register password,
  • changing passwords,
  • recovery answers,
  • backup codes.

Recommended:

Small server

crypto_threads: 2

Medium server

crypto_threads: 4

Large server

crypto_threads: 4-8

Do not set this too high.
If your CPU has 6 cores and you set this to 32, login attempts can overload your CPU.

network_threads

network_threads: 4

How many worker threads can process network/API tasks.

Used mainly for:

  • Premium Auto-Login Mojang API checks,
  • external network operations.

Recommended:

network_threads: 2-4

For most servers, 4 is enough.

queue_size

queue_size: 512

Maximum number of queued async tasks per worker group.

This prevents unlimited task creation.

Example:

If 200 players all type /login at once, PureAuth will queue work instead of spawning unlimited threads.

Recommended:

Small server

queue_size: 128

Medium server

queue_size: 256

Large server/network

queue_size: 512

Very large networks can use:

queue_size: 1024

Do not set this absurdly high unless you know why.
A giant queue can hide overload instead of solving it.

Network configuration

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

This section is for network/proxy behavior.

network.mode

mode: "LOCAL"

Available values:

LOCAL
REDIS

LOCAL

Default mode.

Use this when:

  • you have one standalone Paper server,
  • or one proxy instance,
  • or one normal backend network path.

In LOCAL mode, PureAuth uses normal plugin messaging and local memory/session state.

This is the currently active production mode.

REDIS

Reserved for future multi-proxy shared session state.

Important:

In PureAuth 6.0.0, Redis config exists, but Redis sync is not fully implemented yet.

That means:

Do not enable REDIS expecting full multi-proxy Redis synchronization yet.

For now, keep:

mode: "LOCAL"

unless Redis support is finished in a future release.

network.redis

This section prepares connection details for Redis.

Current status:

Prepared in config, not fully active yet.

host

host: "localhost"

Redis server host.

Example:

host: "127.0.0.1"

port

port: 6379

Default Redis port.

password

password: ""

Redis password.

Empty means no password.

Example:

password: "myStrongRedisPassword"

database

database: 0

Redis database index.

Default:

0

channel

channel: "pureauth:network"

Redis pub/sub channel name planned for PureAuth network messages.

Recommended to leave unchanged.

Settings configuration

settings:
  safe_mode: false
  language: "EN"
  blindness_effect: true

safe_mode

safe_mode: false

If enabled, sensitive admin commands can only be used from console.

Affected commands:

/pureauth unlock
/pureauth unregister
/pureauth register
/pureauth forcelogin
/pureauth setpassword

Recommended for public production servers:

safe_mode: true

This protects against compromised admin accounts.

language

language: "EN"

Available:

EN
PL

Example:

language: "PL"

blindness_effect

blindness_effect: true

If enabled, unauthenticated players get blindness effect during ghost mode.

Ghost mode is used before login/register to prevent players from interacting normally before authentication.

Premium Auto-Login

premium_login:
  enabled: true
  require_same_ip: true

enabled

enabled: true

Enables /premium.

If disabled, players cannot enable Premium Auto-Login.

require_same_ip

require_same_ip: true

If enabled, Premium Auto-Login only works when the player's IP matches the last saved IP.

Recommended:

require_same_ip: true

This is safer.

If disabled:

require_same_ip: false

Premium players may auto-login even if their IP changes.

Backup system

backup:
  enabled: true
  interval_hours: 24
  max_backups: 10

enabled

Enables automatic backups.

enabled: true

interval_hours

How often backups are created.

interval_hours: 24

This means once every 24 hours.

max_backups

Maximum number of backup files to keep.

max_backups: 10

Older backups are removed automatically.

Recovery system

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

enabled

Enables or disables /recovery.

enabled: true

questions

List of available recovery questions.

Players choose one question during /recovery setup.

You can translate or customize them.

Example:

questions:
  - "Jak miał na imię twój pierwszy zwierzak?"
  - "W jakim mieście się urodziłeś?"
  - "Jaki jest twój ulubiony kolor?"

Important:

Do not reorder/remove questions carelessly if players already configured recovery.
The plugin stores question ID, so changing order may make old accounts display a different question.

Discord webhooks

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

enabled

Enables Discord webhook notifications.

enabled: true

webhook_url

Discord webhook URL.

webhook_url: "https://discord.com/api/webhooks/..."

events

Controls which events are sent.

Examples:

user_register: true
failed_attempts: true
account_locked: true
admin_sensitive: true

Recommended:

Keep sensitive admin actions enabled if you want audit logs.

Security settings

security:
  account_lock_enabled: true
  kicks_before_lock: 3

account_lock_enabled

If enabled, accounts can be locked after too many failed attempts/kicks.

account_lock_enabled: true

kicks_before_lock

How many failed login kick events are allowed before account is locked.

kicks_before_lock: 3

If a player repeatedly fails login and reaches this limit, account becomes locked and must be unlocked by admin.

Admin unlock command:

/pureauth unlock <player>

CAPTCHA

captcha:
  enabled: true
  length: 5
  characters: "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"

enabled

If enabled, registration requires CAPTCHA.

enabled: true

Then players must use:

/register <password> <password> <captcha>

If disabled:

/register <password> <password>

length

Length of generated CAPTCHA.

length: 5

characters

Characters used for CAPTCHA generation.

characters: "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"

Login limits

login_timeout: 60
max_attempts: 3
min_password_length: 4
max_accounts_per_ip: 3

login_timeout

How many seconds player has to login/register before being kicked.

login_timeout: 60

max_attempts

How many wrong login attempts are allowed before kick.

max_attempts: 3

min_password_length

Minimum password length.

min_password_length: 4

Recommended:

min_password_length: 6

or higher.

max_accounts_per_ip

Maximum number of accounts from the same IP.

max_accounts_per_ip: 3

Useful against account spam.

Sessions

sessions:
  enabled: true
  time_minutes: 1

enabled

If enabled, players can reconnect without logging in again for a short time.

enabled: true

time_minutes

How long the session lasts.

time_minutes: 1

Example:

time_minutes: 5

Means session is valid for 5 minutes after logout.

Admin Guard

admin_guard:
  enabled: true

If enabled, players with this permission:

pureauth.admin.guard

must enable 2FA.

Recommended:

Give pureauth.admin.guard to owners, admins and staff accounts.

Update checker

update_checker: true

Checks for plugin updates.

Message interval

message_interval: 10

How often login/register reminder messages are sent.

Value is in seconds.

message_interval: 10

Locations

locations:
  spawn_login: ""
  spawn_register: ""

Do not edit manually unless you know the format.

Use commands:

/pureauth location login
/pureauth location register

Messages

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

PureAuth supports English and Polish messages.

Set language here:

settings:
  language: "EN"

or:

settings:
  language: "PL"

You can edit all messages manually.

12. Recommended configs

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"

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"

Large network

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"

For very large networks, you may test:

maximum_pool_size: 32
database_threads: 8
crypto_threads: 8
queue_size: 1024

But do this only after checking CPU and database usage.

13. Notes for networks

For BungeeCord/Velocity networks:

  • Use MySQL/MariaDB.
  • Install pureauth-paper on backend Paper servers.
  • Install pureauth-bungee or pureauth-velocity on proxy.
  • Keep backend servers in online-mode=false.
  • Keep network.mode: "LOCAL" for now.
  • Redis config is reserved for future multi-proxy shared state.

14. Troubleshooting

Plugin disables itself on startup

Check:

online-mode=false

PureAuth will disable itself if backend server is in online mode.

Players cannot register with /register <pass> <pass>

Check if CAPTCHA is enabled:

captcha:
  enabled: true

If CAPTCHA is enabled, command is:

/register <pass> <pass> <captcha>

SQLite does not work on a network

SQLite is not recommended for proxy networks.

Use:

database:
  type: "MYSQL"

Premium Auto-Login does not work

Check:

premium_login:
  enabled: true
  require_same_ip: true

If require_same_ip is true, player must connect from the same IP as before.

Also make sure Mojang API is reachable.

PlaceholderAPI placeholders do not work

Make sure PlaceholderAPI is installed.

Available placeholders:

%pureauth_logged%
%pureauth_has_2fa%

Admin command says no permission

Give the specific permission.

Example:

pureauth.admin.reload
pureauth.admin.unlock
pureauth.admin.setpassword

Do not rely only on pureauth.admin unless your permissions plugin is configured to inherit children.

15. Quick command reference

Player commands

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

Admin commands

/pureauth
/pureauth reload
/pureauth stats
/pureauth unlock <player>
/pureauth unregister <player>
/pureauth register <player> <password>
/pureauth forcelogin <player>
/pureauth info <player>
/pureauth setpassword <player> <newpass>
/pureauth accounts <IP>
/pureauth location <login|register>

16. Quick permission reference

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

Clone this wiki locally