Permissions overview

This page is the starting point for setting up permissions in your game. It shows the layers that decide what a player can do, the permission keys you work with, and a checklist for configuring them.

All permission configuration is done by app admins (members with the manage_apps permission on the app's organization). manage_apps is a per-user permission checked on the normal bearer token, so admins can configure permissions from any trusted context — including a browser admin tool such as the management UI, not only a backend service. The standing advice is simply to keep a privileged admin token out of the untrusted client you ship to end users.

The three layers

A player's effective abilities come from three layers that stack:

Layer	Where you set it	Scope	Answers
App access + tier	Management API	Whole app	Can this player play, and what does their tier allow everywhere?
Grid permissions	Game API — Grids and permissions	A 3D region	What may this player do in this specific area?
Team roles	Game API — Teams	A team	Who may manage this team, and what does the team grant in the world?
Channel roles	Game API — Channels	A channel	Who may manage this channel, and who may publish to it (send_messages)?

Tiers set the baseline for the whole app. Grids add spatial rules on top — either expanding control in an area (e.g. a player owns their plot) or restricting it (e.g. a safe zone). Teams let you grant and delegate at the group level instead of player-by-player.

Open by default

Permissions are always enforced on the realtime path — every spatial action a player takes is checked against their app access, tier, and grid permissions. There is no "permissions off" mode.

To keep the common case effortless, a new app is open by default:

• Creating an app provisions a default tier that grants all runtime permissions (access, teleport, update_voxel_data, use_voice_chat).
• The app gets a default grid that spans the whole world, and any player you grant app access is automatically granted all permissions on that grid.

So a fresh app behaves like an open sandbox: any entitled player can move, build, and use voice anywhere — no manual grid or grant setup required. You only do the work below when you want to restrict something (a non-building safe zone, plot ownership, members-only areas, etc.). Restriction is opt-in; openness is the default.

Permission keys

Grid and tier permissions use these runtime keys:

Key	Allows
access	Entering / moving / sending events in an area
update_voxel_data	Editing voxels (building)
use_voice_chat	Voice audio

Query the Management API runtimePermissions for the live catalog when building a permission picker in your studio tools.

Teams use a separate set of team-management keys (manage_group, manage_members, manage_roles, invite_members) — see Teams.

Set up permissions for your game

1. Define tiers and what each grants. In the Management API, create your access tiers and choose which permission keys each tier grants app-wide (for example, a free tier with access only, and a builder tier that adds update_voxel_data). This is the baseline every player gets.

2. Decide which regions need finer control. Create grids for those regions. A grid can be a whole zone or a single chunk, so you can hand one player control of exactly one chunk.

3. Cap what a region allows (optional). Use setGridPermissionLimits to make safe zones — e.g. allow access and use_voice_chat but never building, regardless of other grants.

4. Grant permissions in the region. Either:

   • Per player with grantGridPermissions (e.g. give a plot owner update_voxel_data on their chunk), or
   • Per team/role with assignGroupToGrid — grant a whole team (or just members holding a specific role) permissions across a region.

5. Let players run their own teams (optional). Use setTeamPolicy to choose who can create teams (admin / member / anyone) and the default join policy. Team leaders can then manage their own members and roles.

How it's enforced

The realtime layer (the Buddy replication servers) checks permissions on every spatial message — this is always on. A message is accepted only if the sender has active app access whose tier holds the needed key and the target chunk is inside a grid where the sender holds that key. A player without access to a region can't act there, building requires update_voxel_data, and voice requires use_voice_chat; anything else is rejected with UNAUTHORIZED. With the open-by-default setup above this is transparent — the default grid grants every entitled player every key everywhere — until you add narrower grids/limits. A player's effective keys on a grid are:

(their tier baseline) plus (direct grants ∪ team/role grants) on that grid, within the grid's limits.

Use gridUserPermissions (one grid) or nearbyGridPermissions (all grids around a chunk) to see exactly what a player has where.

Related guides

• Grids and permissions — grids, limits, direct and group grants.
• Teams — teams, roles, delegation, and assigning teams to grids.
• Channels — app-wide message channels, the send_messages role, and publishing/receiving channel messages over the realtime UDP path.
• Avatar state and Actor state — owner-exclusive write / public read for character data.