Account Linking

Anonymous vs Authenticated

How to Link

1. Start the Linking Process

Run the following command on your server:

/bench link

/bench link (and /bench link force, which replaces an existing token) requires the voxelbench.link permission on top of voxelbench.use.

2. Receive a Linking Code

The plugin contacts the VoxelBench backend and displays a temporary code and a link. Click the link in chat, or copy it into your browser.

3. Confirm on the Website

Log in to your VoxelBench account (or create one) and confirm the link. The plugin automatically detects when you've confirmed.

4. Done

Once confirmed, the plugin saves an authentication token and switches to authenticated mode in config.yml:

mode: authenticated
authentication:
  token: "your-token"

Important: Never share your authentication token. It grants access to submit reports on behalf of your server.

Re-Linking

If you need to link to a different account:

/bench link force

This replaces the existing token with a new one.

How It Works

The linking process uses a device-code style flow:

1. The plugin sends a request to /api/v1/server/link with your server's identity hash
2. The backend returns a temporary code and a confirmation URL
3. The plugin displays the code and URL to the operator
4. The plugin polls the backend every 5 seconds to check whether the code has been confirmed
5. Once confirmed, the backend returns an authentication token
6. The plugin saves the token and switches to authenticated mode

Timeouts

• The linking code expires after 10 minutes
• The plugin stops polling after 5 minutes; if you confirm later, run /bench link again
• If the code expires, run /bench link again to get a new one

Troubleshooting

"Connection error" when linking

• Ensure your server can make outgoing HTTPS connections (/bench ping helps diagnose it)
• Check that voxelbench.com is not blocked by a firewall
• Try again in a few minutes if the backend is temporarily down

"Already linked" message

Your server already has an authentication token. Use /bench link force to replace it.

"Already in progress" message

"A linking process is already in progress. Please wait." means that a linking attempt is still waiting for confirmation: any other /bench link or /bench link force, typed by you, another player or the console, is refused until it ends. Confirm it on the website, or wait until the plugin stops polling (5 minutes), then run /bench link again if needed.

Token issues

If you experience authentication errors after linking:

1. Check that the token in config.yml is not corrupted
2. Try re-linking with /bench link force
3. Check that the VoxelBench backend is reachable