Bedrock allowlist and operators explained

How allowlist.json and permissions.json really work on a Bedrock server, how Gamertags are matched, and the safe order to switch the allowlist on.

6 min read · Updated Oct 21, 2026 · By GuavaHost Team

A Bedrock server controls two separate things with two separate files. The allowlist decides who may connect at all, and the permission levels decide what they can do once they are in. They live in allowlist.json and permissions.json in your server's root folder, and both can be driven from the Console tab without touching a file. This guide covers the formats, the Gamertag rules that trip people up, and the one mistake that locks you out of your own server.

The allowlist in one paragraph

When allow-list=true in server.properties, the server checks every incoming connection against allowlist.json and turns away anyone not on it. When it is false, the file is ignored and anyone with your address and port can join. There is no middle setting, and Bedrock has no server password, so the allowlist is the tool.

The order that does not lock you out

Add names first, then switch it on. In that order, nothing can go wrong.

1. Open the Console tab on your server page.
2. Run allowlist add YourGamertag for yourself, then one line per friend.
3. Run allowlist list and read the result back. Every name you expect should be there.
4. Only now run allowlist on.

Doing it the other way round, switching the list on while it is empty, means nobody is allowed, including you. It is the single most common Bedrock support question we see. If it happens, you are not locked out of the panel, only the game: open the Console tab and run allowlist off. The console works whether or not you can join, so this is always recoverable. Allowlist and whitelist explained covers the same trap on the Java side, where the word is whitelist.

What happens to someone already online

The check only runs when a player connects. Switching the allowlist on does not kick anyone who is already in the world, and neither does removing a name with allowlist remove. They stay until they disconnect, the server restarts, or you kick them yourself with kick <name> <reason>. So if you turn the list on to get rid of someone, remove them and then kick them, or the change does nothing until they leave on their own.

The allowlist.json format

If you would rather edit the file on the Files tab, it is a JSON array of one object per player:

[
  {
    "ignoresPlayerLimit": false,
    "name": "Steve"
  },
  {
    "ignoresPlayerLimit": false,
    "name": "Alex"
  }
]

• name is the player's Gamertag, which is their Microsoft or Xbox account name.
• ignoresPlayerLimit lets that player in even when the server is at max-players. Handy for yourself on a full server, best left false for everyone else.
• An xuid field may also appear. The XUID is the permanent numeric ID behind an Xbox account, and the server records it once that player has connected successfully.

After editing the file by hand, run allowlist reload in the console so the server picks it up without a restart.

How Gamertags are matched

This is where most of the remaining trouble lives.

• The name has to be the player's current Gamertag, spelled exactly. A typo is simply a different person.
• Gamertags with a space in them need quotation marks in the console: allowlist add "Big Steve 99".
• Modern Gamertags can show a suffix like #1234 in the Xbox app. That part is not in the name the server sees, so leave it off.
• A player who changes their Gamertag stops matching the name entry. If the server already recorded their xuid, they still get in, because the XUID never changes. If not, add the new name.
• There is no partial matching and no wildcards.

The practical trick is to add players by name, let them connect once, and leave the XUID the server writes in place.

Operators and permission levels

Permission levels are the second file. Bedrock has three, and every player has one:

New players get whatever default-player-permission-level says in server.properties, which Minecraft Bedrock server.properties explained covers along with the rest of the file. Note that operator commands also need allow-cheats=true on the world, set in Startup settings on the Settings tab. An operator on a world with cheats off can still kick and manage the server from the console but cannot run gameplay commands such as give.

The quickest way to make someone an operator is from the Console tab:

op Steve
deop Steve

Run these with the player's exact Gamertag, in quotation marks if it has a space. Granting operator while that player is online takes effect for them straight away.

The file version, permissions.json, keys on the XUID rather than the name:

[
  {
    "permission": "operator",
    "xuid": "2535000000000000"
  }
]

That is deliberate: a Gamertag can change, an XUID cannot, so nobody inherits your admin by renaming themselves. The side effect is that you cannot write an entry for someone who has never connected, because you do not have their XUID yet. Let them join once, look up the XUID the server recorded in allowlist.json or in the console connection line, and use it here. Restart the server afterwards so there is no doubt the file has been read.

A sensible setup

For a server for friends: allowlist on, default-player-permission-level=member, and operator only for yourself and anyone you would trust with a world edit. For a public server: allowlist off, default-player-permission-level=member, and a short, deliberate list of operators. Handing out operator freely is the fastest way to end up needing a backup, and Stop griefers on your server has the rest of that argument.

Troubleshooting

• A friend on the list still cannot join. Check the spelling against their Gamertag, confirm allowlist reload has run, and make sure the server is not at max-players. If they are on Xbox, PlayStation or Switch they also cannot enter a server address at all; see Play Bedrock on console.
• The allowlist seems to be ignored. Check allow-list=true in server.properties. Editing only the JSON file does nothing if the setting is off.
• The server will not start after you edited a file. A missing comma or bracket in either JSON file stops the server loading. Paste the file into a JSON validator, fix it, and start again.
• op says the player was not found. Bedrock can only op a name it recognises. Have them connect once first, then run it again.

Common questions

Does the allowlist stop people seeing my server exists?

No. It only refuses the connection. Anyone with your address and port can still try, and they will get an error rather than a quiet rejection. If you want to keep the address itself quiet, do not post it publicly.

Can I give someone admin powers without making them an operator?

Not on Bedrock. There are only the three permission levels, and there is no plugin system to add finer roles, because Bedrock servers do not run plugins. If you need per permission roles, that is a reason to run a Java server instead.

Do allowlist changes need a restart?

No. Run allowlist reload in the console after editing the file, or just use the allowlist add and allowlist remove commands, which apply immediately. Changes to permissions.json are safest with a restart.

Is the allowlist the same as banning someone?

Not quite, although on a private server it does the same job. The allowlist is a list of who may come in, so removing someone and kicking them keeps them out for good. A Bedrock server has no ban list of its own, which is why an open server with the allowlist switched off has fewer options for dealing with one bad player.

Still stuck? Jump into our Discord at discord.gg/GuavaHost and the team will help you out.

• bedrock
• allowlist
• operators
• permissions
• admin
• console

Host a Minecraft Bedrock server From $4.00/mo, with instant setup and DDoS protection.

Still need help? Our team is online 24/7 to answer questions.

Contact support