Projects & teams

Projects scope everything you do on the platform — pushes, previews, members, tokens, and Minecraft access.

Every push, preview, and token belongs to a project. A project is your collaboration unit: a set of members with roles, working on the same plugin or service.

Roles

There are three roles, with strictly nested permissions:

Role	Push	View pushes	Manage previews	Manage Minecraft access	Invite / remove members	Mint tokens
viewer	—	✓	—	—	—	—
editor	✓	✓	✓	✓	—	—
owner	✓	✓	✓	✓	✓	✓

Roles are project-scoped. You can be an owner on one project and a viewer on another.

A project must always have at least one owner. Trying to demote or remove the last owner returns a 409 last owner protection error from forge.

Default project

When you sign up, a default project is created for you with you as the sole owner. You can create more from the portal or via API.

CLI commands without a project flag use your default project. Pin a different one for a single command:

grounds --project <project-id> push

Or for the whole shell session:

export GROUNDS_PROJECT=<project-id>

Inviting members

There are two flows.

Add by username

Owners can add a known account directly from the portal Members page. The user must have signed in at least once so we have a record of them.

Invite link

For people who haven’t signed up yet, mint a one-time invite link:

1. Portal → Project → Members → Invite link.
2. Pick the role (editor or viewer) and an expiry (default 7 days, max 30).
3. Send the URL. The recipient signs in with their Grounds Account and is automatically added to the project.

Invite links are single-use — redemption is atomic, so simultaneous clicks can’t both succeed. They cannot be used to grant owner (only existing owners can promote).

Minecraft access

Minecraft access is project-scoped by default, with an optional app-specific layer for one Minecraft app.

There are three sources:

Source	Managed from	Access granted
Linked project member	Members page	Every Minecraft app in the project
Project-wide player	Members page → Minecraft whitelist	Every Minecraft app in the project
App-specific player	App settings → Minecraft whitelist	Only that app

Project members who sign in with a linked Minecraft Java account appear as Linked member entries. These entries inherit access from membership and are read-only in the whitelist list. To remove that access, remove the project member or update the member’s linked Minecraft identity.

Owners and editors can add Project-wide players from the Members page. Use this for playtesters or operators who need to join Minecraft servers but should not access the project in the portal.

Owners and editors can add App-specific players from a Minecraft app’s settings page. Use this for temporary access to one server without granting access to every Minecraft app in the project.

When you add a Minecraft username, forge resolves it to a Mojang UUID immediately. The UI continues to show the username, but access is tied to the UUID so later username changes do not strand the whitelist entry.

Only Java identities are used for Minecraft app access today. Bedrock ownership from the identity provider does not grant Java server access.

Service-account tokens

For unattended use (CI, scripts, bots) projects can mint long-lived gnds_* API tokens scoped to a single project. See CI / service-account tokens.

Audit

Membership, role, token, deployment, push, project, and Minecraft whitelist changes are recorded in the project’s audit feed (visible in the portal under Audit).