How to Set Up a Whitelist on Bedrock Server

Why Use a Whitelist

A whitelist restricts your server to approved players only. Anyone not on the list is denied entry at the login screen. This is essential for private community servers, beta testing, events or any scenario where open access is not wanted. Setting up a whitelist bedrock server is simpler than it sounds and only takes a few minutes.

Whitelist on Bedrock Dedicated Server

Enabling the Whitelist

Open server.properties and set:

white-list=true

Restart the server. From this point, only players listed in allowlist.json can connect.

Adding Players via Console

The fastest way to add players is through the server console:

allowlist add PlayerName

This adds the player by their Xbox Live gamertag. You can also remove players:

allowlist remove PlayerName

And view the current list:

allowlist list

Changes take effect immediately, no restart needed.

Editing allowlist.json Directly

The whitelist is stored in allowlist.json in the server root directory. You can edit it manually:

[
  {
    "ignoresPlayerLimit": false,
    "name": "PlayerOne",
    "xuid": "1234567890123456"
  },
  {
    "ignoresPlayerLimit": true,
    "name": "AdminPlayer",
    "xuid": "6543210987654321"
  }
]

Each entry needs a name (the Xbox gamertag) and an xuid (Xbox User ID). The XUID is a 16-digit number that uniquely identifies a Bedrock player. You can find a player's XUID by having them join the server once (it appears in the server log) or by using an online XUID lookup tool.

The ignoresPlayerLimit flag lets specific players join even when the server is full. Useful for admins and moderators who need guaranteed access.

Host any Bedrock or crossplay server with zero config headaches. Astroworld Hosting supports Geyser, BDS, and every server type on every plan.

Whitelist on PocketMine

PocketMine has built-in whitelist support. To enable it, open server.properties and set:

white-list=on

Then use console commands to manage the list:

whitelist add PlayerName
whitelist remove PlayerName
whitelist list
whitelist on
whitelist off

PocketMine stores the whitelist in white-list.txt, one player per line. You can edit this file directly and reload with whitelist reload.

Whitelist on Nukkit

Nukkit follows the same pattern. Enable the whitelist in server.properties:

white-list=on

Use commands:

whitelist add PlayerName
whitelist remove PlayerName
whitelist list

The whitelist bedrock server configuration on Nukkit stores entries in white-list.txt by default. Some Nukkit forks support JSON format instead.

XUID vs Gamertag

Bedrock players are identified by their Xbox User ID (XUID), not just their gamertag. Gamertags can be changed, but XUIDs are permanent. When you add a player via the console command, BDS looks up and stores the XUID automatically. If you edit allowlist.json manually, include the correct XUID to avoid authentication issues.

If you enter a name without an XUID, BDS will fill it in the next time that player tries to connect (whether successfully or not). But for a clean whitelist bedrock server setup, providing the XUID upfront is more reliable.

Managing a Growing Whitelist

For small servers (under 50 players), manual management is fine. For larger communities, consider these approaches:

• Application system: Have players fill out a form (Google Forms, a Discord bot, or a website form) and add approved players to the whitelist.
• Discord bot integration: Bots like GeyserConnect or custom scripts can link Discord accounts to Xbox gamertags and automatically whitelist verified members.
• Automated scripts: Write a script that reads from a database or spreadsheet and updates allowlist.json programmatically.

See crossplay in action: Astroworld MC, IP play.astroworldmc.com, Java + Bedrock.

Whitelist vs Permissions

The whitelist only controls who can connect. It does not affect what players can do once they are in. Use operator levels (permissions.json) or a permissions plugin to control in-game abilities. On BDS, permissions.json maps XUIDs to permission levels (visitor, member, operator). On PocketMine and Nukkit, use a permissions plugin like PurePerms or LuckPerms.

Troubleshooting

• Player cannot join despite being on the list: Verify the gamertag spelling and XUID. Gamertags are case-insensitive but must match exactly in allowlist.json. If the player changed their gamertag recently, their XUID stays the same but the name field needs updating.
• Whitelist commands not working: Make sure white-list=true (or on) is set in server.properties. Some server software requires a restart after enabling.
• All players kicked after enabling whitelist: Only players already in allowlist.json can remain. Add all current players before enabling the whitelist, or enable it during off-hours and add players from the console.