> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grounds.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# In-Game Permissions

> Manage Minecraft network authorization and integrate local permission checks in Grounds runtimes.

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.

> [!NOTE]
>
> In-game permissions are separate from [Portal access](https://docs.grounds.gg/build/portal/control-center-access.md).
> 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](https://docs.grounds.gg/reference/plugins/in-game-permissions/administration.md)**
>
> Create roles, map Keycloak groups, grant player exceptions, and inspect effective access.

> **[Integrate a runtime](https://docs.grounds.gg/reference/plugins/in-game-permissions/runtime-integration.md)**
>
> Configure the Velocity plugin or Minestom module and make local permission checks.

> **[Register permission nodes](https://docs.grounds.gg/reference/plugins/in-game-permissions/permission-catalog.md)**
>
> Publish your workload's permission catalog and manage custom entries.

> **[Understand the infrastructure](https://docs.grounds.gg/reference/plugins/in-game-permissions/infrastructure.md)**
>
> 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

```mermaid theme={null}
flowchart LR
  defaultRole[Default role] --> roles[Effective Minecraft roles]
  keycloakGroup[Keycloak group] --> groupMapping[Group to role mapping]
  groupMapping --> roles
  directRole[Direct player to role assignment] --> roles
  roles --> inheritedRole[Inherited roles]
  inheritedRole --> roleGrants[Role allow or deny grants]
  roles --> roleGrants
  roleGrants --> policy[Effective policy]
  directGrant[Direct player permission grant] --> policy
  policy --> snapshot[Effective snapshot]
```

| 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.

## Next steps

* [Manage in-game permissions in Portal](https://docs.grounds.gg/reference/plugins/in-game-permissions/administration.md)
* [Configure Velocity or Minestom](https://docs.grounds.gg/reference/plugins/in-game-permissions/runtime-integration.md)
* [Set up the Minecraft Keycloak identity provider](https://docs.grounds.gg/deploy/keycloak-minecraft-idp.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.