How to Set and Protect the Velocity Forwarding Secret

Direct answer

The secret in Velocity’s forwarding.secret file must match each modern-forwarding backend. It authenticates forwarded player details; publishing it or using inconsistent values can allow impersonation or reject legitimate joins.

Recommended procedure

1. Stop the proxy and backend before changing the secret. Identify the forwarding-secret-file value in velocity.toml.
2. Read the generated secret file in a secure editor and copy its contents without whitespace changes to config/paper-global.yml under proxies.velocity.secret on every backend.
3. Check backend online-mode alignment and verify that server.properties online-mode is false only for properly protected proxy backends.

What to change

# config/paper-global.yml (recent Paper)
proxies:
  velocity:
    enabled: true
    secret: "MATCH_THE_PROXY_SECRET"

1. Limit access to the secret file and backups containing it. Never include real tokens in screenshots, support tickets or public repositories.
2. If exposed, generate a new secret, update every backend in the same maintenance window, restart and retest; keep firewall protections active throughout.

How to verify the result

Connect through the proxy, confirm forwarding succeeds and attempt no public backend access. Inspect login errors if secrets differ across servers.

Version and compatibility notes

Paper 1.18.2 and earlier store Velocity support under older paper.yml keys. This guide’s paper-global.yml example targets newer Paper; verify your exact backend version before editing.

Official references

• Velocity modern forwarding
• Velocity security

Related guides