Minecraft ops.json Generator

What is ops.json?

This ops.json generator writes the file that tells a Minecraft server who its operators are. Paste your staff's usernames above and press the lookup button. The tool asks the Mojang API for each UUID, and you pick a permission level from 1 to 4 and whether the player may join a full server. Players that were not found are listed under the form and left out of the file.

Operators, or ops, are players with access to server commands. Vanilla Minecraft has no ranks or groups beyond that: a player is either an operator with a level, or a normal player. The list lives in ops.json, in the server's main folder next to server.properties. Vanilla, Spigot, Paper, Purpur, Fabric and Forge all read the same file.

Most people never open ops.json, because /op <name> writes it for them. You need the file itself when you want to give different players different levels, when you set up a new server and want the staff list in place before the first start, or when you copy the same staff to several servers on a network.

Ask the AI assistant

The AI assistant under the generator reads the ops.json you've built and answers questions about it: what each op level allows, why an operator has no powers after a restart, or how ops work behind a proxy. It's free, with 20 questions a day.

The ops.json format

ops.json is a JSON array with one object per operator:

[
  {
    "uuid": "069a79f4-44e9-4726-a5be-fca90e38aaf5",
    "name": "Notch",
    "level": 4,
    "bypassesPlayerLimit": false
  },
  {
    "uuid": "853c80ef-3c37-49fd-aa49-938b674adae6",
    "name": "jeb_",
    "level": 2,
    "bypassesPlayerLimit": true
  }
]

• uuid is the account UUID in the dashed form. The server matches players on it, so an operator keeps their rights after a name change
• name is the name at the time the entry was written. It is a label for people reading the file; the server does not use it to find players
• level is the permission level, a whole number from 1 to 4
• bypassesPlayerLimit lets the player join when the server already has max-players players online

The keys are the ones the server itself writes, in the same order, so the file looks like one the server made. An empty list is [].

Operator permission levels

Each level includes everything the levels below it allow.

In practice:

• Level 4 is for the owner and people you trust with the whole server. They can stop it and turn off saving
• Level 3 is a moderator: they can deal with players but cannot shut the server down. Note that level 3 includes /op, so a level 3 operator can make other players operators
• Level 2 is a builder or event helper who needs creative mode, teleporting and command blocks, but should not ban anyone
• Level 1 is rarely useful on its own. It lets trusted players build near spawn without giving them any commands

The console always runs at level 4, whatever ops.json says.

How op-permission-level fits in

server.properties has an op-permission-level setting, 4 by default. It is the level that /op <name> gives. Change it to 3 and every new /op makes a moderator instead of a full admin. It does not change entries already in ops.json, and it does not limit what you write in the file.

There is no command to give one player a different level from the others. Editing ops.json is the only way, which is what this tool is for. The server.properties generator sets op-permission-level, function-permission-level (the level that datapack functions run at, 2 by default) and spawn-protection, the radius that level 1 bypasses.

The bypassesPlayerLimit setting

max-players in server.properties caps how many players can be online. When the server is full, new players get "The server is full!" and cannot join. An operator with bypassesPlayerLimit: true can join anyway, even though that puts the server over the limit.

Turn it on for the staff who need to get in when something goes wrong on a busy server, such as a griefer who has to be banned at peak time. Leave it off for everyone else so the limit still means something. Spigot and Paper honour the flag too.

Operators on Spigot and Paper

On plugin servers, op levels only matter for vanilla commands. Plugins use Bukkit's permission system, and any operator counts as "op" there, whatever their level. A permission that a plugin gives to ops by default, which is most admin permissions, goes to a level 1 operator just as much as to a level 4 one.

So on Spigot, Paper and Purpur:

• A level 1 or level 2 operator is not a limited operator. They get every plugin permission that defaults to op, which often includes plugin commands for bans, economy changes and world edits
• For real staff ranks, use a permissions plugin instead. LuckPerms lets you make moderator, builder and helper groups with exactly the permissions each needs, and none of them need to be operators
• Keep ops.json for the owner and one or two admins, with level 4

The EssentialsX setup guide lists the permissions its commands need, which is a good starting point for a moderator group.

How to install the file

1. Generate ops.json with the tool above and download it
2. Stop the server. There is no command to reload ops.json, and the server writes its own copy whenever someone uses /op or /deop, so a file replaced while the server runs can be overwritten
3. Put the file in the server's main folder, replacing the old one
4. Start the server and check the console log for errors about ops.json

If you only need to add one operator at the default level, op <name> in the console is quicker than editing the file.

Operators and the whitelist

Operators can always join a whitelisted server, even when they are not in whitelist.json, so you do not need to add them to both lists. The other side of that: someone you removed from the whitelist can still join if they are still an operator. The whitelist generator writes whitelist.json from the same kind of name list, and its article covers enforce-whitelist and the whitelist commands.

Online mode, offline mode and proxies

The UUIDs in the file are online-mode account UUIDs, the ones the UUID lookup tool returns. They match on any server with online-mode=true.

On a server with online-mode=false, the server makes its own UUIDs from player names, and those never match the ones in this file. More importantly, offline mode lets anyone join with any name. An attacker who types your admin's name gets your admin's operator rights. Never keep operators on an offline server that the public can reach.

The exception is a backend behind a Velocity or BungeeCord proxy with player info forwarding. The proxy checks every player with Mojang and passes the real UUID on, so the backend sees the same UUIDs this tool writes. Forwarding also has to be secure: with BungeeCord's legacy forwarding, a backend that can be reached directly on its own port lets anyone pretend to be anyone. Firewall the backends so only the proxy can connect, or use Velocity's modern forwarding. The Velocity config builder and the BungeeCord config generator cover both setups.

Operators are per server. On a network, each backend has its own ops.json, and the proxy has none. Copy the file to every backend where staff need commands, and give lobby or minigame servers a shorter list if some staff should only have rights on the survival server.

Common mistakes

• Replacing the file while the server runs. The next /op or /deop writes the server's old list back. Stop the server first
• Giving everyone level 4. Moderators do not need /stop. Use level 3 for moderators and level 2 for builders
• Relying on op levels for plugin permissions. On Spigot and Paper any op level gets every op-default plugin permission. Use a permissions plugin for ranks
• Operators on an offline-mode server. Anyone can log in as them. Use online-mode=true, or a proxy with forwarding
• Levels outside 1 to 4. Other numbers are not valid levels. The tool only offers 1 to 4
• Broken JSON after a hand edit. A missing comma or quote makes the file unreadable. The generated file is always valid; validate the JSON again if you change it by hand
• Forgetting other servers on a network. A new admin opped on one backend has no rights on the others until their ops.json is updated too

Keeping staff access tidy

A few habits keep the operator list safe over time:

• Review ops.json when staff step down, and remove them with deop <name> or by regenerating the file
• Keep the number of level 4 operators small. Every one of them can stop the server and turn off saving
• Log in with your operator account only when you need it, or use a separate account for playing, so a stolen session cookie on your main account does less damage
• Protect builds and logs with anti-grief plugins, so a mistake by an operator can be rolled back. The anti-grief plugins guide covers the common choices