The files
| File | Holds | Fields in each entry |
|---|---|---|
whitelist.json | Players allowed in when the whitelist is on | uuid, name |
ops.json | Operators | uuid, name, level, bypassesPlayerLimit |
banned-players.json | Banned accounts | uuid, name, created, source, expires, reason |
banned-ips.json | Banned IP addresses | ip, created, source, expires, reason |
usercache.json | Names and UUIDs of players the server has looked up recently | name, uuid, expiresOn |
Example entries
A whitelist entry. The Whitelist Creator writes files in this format:
[
{
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
"name": "Notch"
}
]An operator entry. level is the operator’s permission level (new operators get the op-permission-level value, 4 by default), and bypassesPlayerLimit lets the operator join when the server is full:
[
{
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
"name": "Notch",
"level": 4,
"bypassesPlayerLimit": false
}
]A ban entry. Dates use the format yyyy-MM-dd HH:mm:ss Z, source is who issued the ban, and expires is forever for a permanent ban:
[
{
"uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
"name": "Notch",
"created": "2026-09-15 18:30:00 +0000",
"source": "Server",
"expires": "forever",
"reason": "Example ban"
}
]Editing these files
- Prefer commands while the server runs:
/whitelist,/op,/deop,/ban,/ban-ip,/pardonand/pardon-ip. They update the files for you. - The server saves its in-memory lists when they change, which can overwrite edits made to the files in the meantime. Edit the files while the server is stopped, or use
/whitelist reloadfor the whitelist. - A name that is out of date in these files doesn’t matter. The server goes by the UUID.
usercache.jsonis a cache. The server rebuilds it, so there is no need to edit it.
Bedrock Dedicated Server
Bedrock uses different files: allowlist.json for its allowlist and permissions.json for player permissions, with players identified by Xbox user ID (XUID) instead of UUID.