How to Whitelist Players on a Minecraft Bedrock Server

To whitelist players on a Minecraft Bedrock server, set allow-list=true in server.properties, restart, then type allowlist add "Gamertag" in the server console for each friend. Bedrock calls it the allowlist, not the whitelist, and stores it in allowlist.json. Once it is on, anyone not on the list gets "You are not invited to this server" when they try to join.

Short answer

1. Stop the server.
2. In server.properties, set allow-list=true.
3. Start the server.
4. In the console, run allowlist add "YourGamertag" first, then one line per friend.
5. Check it with allowlist list.

Add yourself first. It is easy to lock yourself out of your own server.

Whitelist or allowlist?

Same thing. Mojang renamed the Bedrock whitelist to allowlist a few years ago. The file went from whitelist.json to allowlist.json, the property became allow-list, and the command became allowlist. Old guides and old servers still say whitelist. On a current Bedrock Dedicated Server (BDS), use allowlist everywhere.

Step 1: Turn the allowlist on

The allow-list property in server.properties defaults to false, which means anyone with your address can join. Set it to true:

allow-list=true

BDS reads server.properties only on startup, so restart after the change.

On GamezServers, open Settings and set Allowlist to On, only players I add, then restart. No file editing needed.

Step 2: Add players by Gamertag

In the server console (no slash):

allowlist add "Steve Builder"
allowlist add "AlexTheMiner"

Rules that save you a support ticket:

• Use the Gamertag, not the Minecraft display name or the Microsoft email. Every Bedrock player signs in with a Microsoft account, and the Gamertag is the name on that account. Players can see it on the Minecraft start screen or at account.xbox.com.
• Quote names with spaces. allowlist add Steve Builder only adds "Steve". Quotes are harmless on names without spaces, so always use them.
• Copy it exactly. Ask each friend for the Gamertag exactly as Minecraft shows it on their profile, including any numbers at the end. A near miss is the most common reason an added player still gets rejected.

From in game chat, operators can run /allowlist add "Name" too, but that needs cheats on. The console always works.

On GamezServers, the Allowlist player button asks for the Gamertag and runs allowlist add "Gamertag" for you.

Step 3: Check and remove

allowlist list
allowlist remove "AlexTheMiner"

Removing someone does not kick them if they are online. Run kick "AlexTheMiner" as well.

How allowlist.json works

The command writes to allowlist.json in the main server folder, next to server.properties. You can also edit it yourself:

[
  {
    "ignoresPlayerLimit": false,
    "name": "Steve Builder"
  },
  {
    "ignoresPlayerLimit": true,
    "name": "AlexTheMiner",
    "xuid": "2535412345678901"
  }
]

After editing the file by hand while the server runs, type allowlist reload so BDS reads it. Keep the JSON valid: a missing comma or bracket and the server cannot read the list. If in doubt, paste it into any JSON validator first.

Gamertag vs XUID: which one should you use?

Use the Gamertag. That is how the allowlist is designed to work.

The XUID is a long number that belongs to the Microsoft account and never changes. You do not need to look it up. When a listed player connects for the first time, BDS matches them by name and writes their XUID into the file. You will see it in the console too, in a line like Player connected: AlexTheMiner, xuid: 2535412345678901.

Where XUIDs do matter:

• Gamertag changes. Players can change their Gamertag. If someone changes theirs, add the new name. Their XUID is the same account, so their inventory and position on the server stay with them.
• permissions.json. The operator list is stored by XUID, not by name. That is why op only works on someone who is online, and why you need the XUID to op someone by hand.

ignoresPlayerLimit: a slot for the owner

Set "ignoresPlayerLimit": true on yourself and your admins so you can always get on a full server. Microsoft's docs say there is still a soft cap of 30 players or one more than max-players, whichever is higher, so it is a few spare seats, not unlimited.

Allowlist errors and what they mean

• "You are not invited to this server": the allowlist is on and the Gamertag is not on it, or it is spelled differently. Check allowlist list against the exact Gamertag.
• Added but still rejected: the name in the file has a typo or is missing the numbers some Gamertags end with. Remove it and add the exact Gamertag again.
• Edited the file, nothing changed: run allowlist reload, or restart.
• Allowlist does nothing: allow-list is still false, or you changed it without restarting.
• Friend on a child account: the allowlist is not the problem. Their Xbox privacy settings may block multiplayer. See Bedrock "Unable to connect to world" fix.

What the allowlist does not do

It keeps unknown players out, and that is all. It does not give anyone permissions, and Bedrock has no ban command or ban list. To deal with someone who is already on the list, remove them and kick them. For operators, see the op and permission commands in our Bedrock server commands list.

The quick way on GamezServers

Turn on Allowlist in Settings, restart, then use Allowlist player for each friend and Make operator for whoever helps you run things. Share the address with the join instructions for consoles if anyone plays on Xbox, PlayStation or Switch. New to hosting? Start at Minecraft Bedrock server hosting.

FAQ

Is Bedrock's allowlist on by default?

No. allow-list defaults to false in server.properties, so a new server accepts anyone who has the address. Turn it on before you share the address outside your group.

Can I add a player to the allowlist while they are offline?

Yes. allowlist add works whether or not the player is online. They can join the next time they try.

Do console and phone players work with the allowlist?

Yes. Every Bedrock player has a Microsoft account Gamertag, whether they play on Xbox, PlayStation, Switch, phone or PC. Add that Gamertag like anyone else.

Does the Bedrock allowlist use UUIDs like Java?

No. Bedrock uses the Gamertag in name and the Xbox user ID in xuid. There are no Java style UUIDs in allowlist.json.

Can I copy a Java whitelist.json to Bedrock?

No. Java uses Mojang account names and UUIDs, Bedrock uses Microsoft Gamertags and XUIDs. Add each Bedrock player by Gamertag instead.