In-Game Permissions

Use Minecraft permissions to control what players can do across a Grounds network. Administrators create policy in Portal; Velocity and Minestom workloads receive complete permission snapshots and check them locally.

In-game permissions are separate from Portal access. Portal access decides who can administer the platform. Minecraft permissions decide what a player may do inside the Minecraft network.

Choose your task

Manage permissions

Create roles, map Keycloak groups, grant player exceptions, and inspect effective access.

Integrate a runtime

Configure the Velocity plugin or Minestom module and make local permission checks.

Register permission nodes

Publish your workload’s permission catalog and manage custom entries.

Understand the infrastructure

Learn how production, stage, and project permission environments stay isolated.

Permission environments

Grounds keeps policy separate between production, stage, and individual projects. Production owns the platform’s live Minecraft policy. Stage provides an isolated pre-production policy environment. Each project owns its local policy, which you can initialize or update from production through an explicit preview and import workflow.

Authorization model

Term	Meaning
Keycloak group	Read-only identity input that can map to a Minecraft role.
Minecraft role	Reusable grants; it can inherit another role or be a default role.
Grant	Allow or deny rule at global, environment, server-type, or server scope.
Environment	Deployment context such as `stage` or `prod` used for scoped checks.
Group-to-role mapping	Assigns a Minecraft role to every player in one Keycloak group; it can expire.
Direct player-to-role assignment	Assigns a reusable role to one player; it can expire.
Direct player grant	Time-limited or permanent exception for one player.
Effective snapshot	Complete, versioned result evaluated locally by a runtime.

Assignment sources

Source	Assignment	Result
Default role	Role -> every player	The role’s grants apply to every player.
Keycloak group mapping	Keycloak group -> role	Members receive the mapped role and its inherited roles.
Direct role assignment	Player -> role	One player receives the selected role and its inherited roles.
Direct player grant	Player -> permission node	One player receives an allow or deny exception without a role.

Keycloak groups never map directly to permission nodes: they provide group-to-role assignments. A role can then carry allow or deny grants, including inherited role grants. Exact patterns such as network.chat.moderate and wildcards such as network.chat.* can match a check. Server scope wins over server-type scope, server-type scope wins over environment scope, and environment scope wins over global scope. A deny wins between equally specific candidates. Once a snapshot expires, a check returns false until a valid replacement is available. Changing a permission does not disconnect a player automatically.

Plugins SDK

Convention plugins

Development libraries

Conventions

Choose your task

Manage permissions

Integrate a runtime

Register permission nodes

Understand the infrastructure

Permission environments

Authorization model

Assignment sources

Next steps

​Choose your task

Manage permissions

Integrate a runtime

Register permission nodes

Understand the infrastructure

​Permission environments

​Authorization model

​Assignment sources

​Next steps

Choose your task

Permission environments

Authorization model

Assignment sources

Next steps