# How to Whitelist Players on Your Minecraft Bedrock Server (/docs/minecraft-bedrock/whitelist)



import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import { Step, Steps } from 'fumadocs-ui/components/steps';

The allowlist (formerly called whitelist) restricts your server to only approved players. When enabled, anyone not on the list gets rejected at connection.

> Bedrock renamed the command from `whitelist` to `allowlist` in newer versions. Both work, but use `allowlist` going forward.

Enable the Allowlist [#enable-the-allowlist]

<Steps>
  <Step>
    Open server.properties [#open-serverproperties]

    In the [XGamingServer Panel](https://panel.xgamingserver.com), click **Files** in the sidebar and open `server.properties`.

    {/* Screenshot needed: File Manager showing server.properties */}
  </Step>

  <Step>
    Set allow-list to true [#set-allow-list-to-true]

    Find this line and change it:

    ```properties
    allow-list=true
    ```

    Click **Save Content**.
  </Step>

  <Step>
    Restart the server [#restart-the-server]

    Go to **Console** and restart. The allowlist is now active — only listed players can join.
  </Step>
</Steps>

Managing Players [#managing-players]

<Tabs items={['Console Commands', 'Edit allowlist.json']}>
  <Tab value="Console Commands">
    Run these in **Console** while the server is running:

    | Command                         | What it does                                               |
    | ------------------------------- | ---------------------------------------------------------- |
    | `allowlist add "PlayerName"`    | Add a player (quotes required — gamertags can have spaces) |
    | `allowlist remove "PlayerName"` | Remove a player                                            |
    | `allowlist list`                | Show all allowed players                                   |
    | `allowlist reload`              | Reload the file after manual edits                         |

    > The player does **not** need to be online to be added. The server will resolve their XUID automatically when they first connect.
  </Tab>

  <Tab value="Edit allowlist.json">
    <Steps>
      <Step>
        Open the file [#open-the-file]

        In **Files**, open `allowlist.json` in the root directory.
      </Step>

      <Step>
        Add entries [#add-entries]

        Each player needs a JSON object with their gamertag. The XUID is optional — the server fills it in automatically on first connection.

        ```json
        [
          {
            "ignoresPlayerLimit": false,
            "name": "PlayerOne"
          },
          {
            "ignoresPlayerLimit": true,
            "name": "AdminPlayer",
            "xuid": "2535416790845590"
          }
        ]
        ```
      </Step>

      <Step>
        Save and reload [#save-and-reload]

        Click **Save Content**, then run `allowlist reload` in **Console** to apply without restarting.
      </Step>
    </Steps>
  </Tab>
</Tabs>

allowlist.json Fields [#allowlistjson-fields]

| Field                | Required | Description                                                                                |
| -------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `name`               | Yes      | Player's Xbox gamertag (exact match, case-insensitive)                                     |
| `xuid`               | No       | Xbox User ID. Auto-filled on first connect if left blank                                   |
| `ignoresPlayerLimit` | No       | If `true`, this player can join even when the server is at max capacity. Useful for admins |

How It Works With online-mode [#how-it-works-with-online-mode]

The allowlist requires `online-mode=true` (the default). With `online-mode=false`, the server cannot verify Xbox identities, so the allowlist becomes name-based only — which can be spoofed.

Common Issues [#common-issues]

| Problem                              | Fix                                                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| Player can't join but is on the list | Check for typos in the gamertag. Run `allowlist list` to verify. If the XUID is wrong, remove it and let the server re-resolve |
| "You are not on the allowlist"       | The player's gamertag may have changed. Remove the old entry and re-add with the new name                                      |
| allowlist.json is empty `[]`         | This is normal for a new server. Add players via console or edit the file                                                      |
| Changes don't take effect            | Run `allowlist reload` in Console, or restart the server                                                                       |

Related Guides [#related-guides]

* [Give OP Permissions](/docs/minecraft-bedrock/op-setup)
* [Server Properties](/docs/minecraft-bedrock/server-properties)
* [Connect to Your Server](/docs/minecraft-bedrock/join-server)