Core Concepts

Accounts, workspaces, environments, memberships, and the ReBAC authorization model.

Groundfloor organizes resources in a hierarchy. Understanding this model is essential for both portal users and API integrators.

Resource hierarchy

Account (billing org, customer tenant)
  └── Workspace (tenant boundary — UUID)
        └── Environment (dev / staging / prod)
              └── App (slug, manifest, releases)

Resource	Identifier	Scope
Account	UUID	Billing, membership, offboarding
Workspace	UUID	Data, secrets, files, apps — your tenant boundary
Environment	slug	Promotion target (dev → staging → prod)
App	slug	Federated remote or Coderunner workload

Membership and roles

A human user (sub from Keycloak) can belong to multiple accounts. Within each account, they hold a membership with a role:

Role	Typical permissions
`owner`	Full account administration
`admin`	Manage workspaces, members, most pillars
`member`	Read/write on assigned workspaces

Authorization is enforced via SpiceDB ReBAC — not role strings alone. The closed action vocabulary includes: administer, read, write, delete, ddl, deploy, manage_members, view_billing.

Two identity planes

Do not conflate Control Plane auth with workspace site auth — they are separate product features.

Plane	Purpose
Control Plane auth	Signing into `app.groundfloor.cloud` / `admin.groundfloor.cloud` against the shared platform Keycloak realm
Workspace site auth	Optional per-subdomain login with per-workspace IdP and branding

Workspaces can register apps and run workloads without Groundfloor Shell or Groundfloor Auth.

Customer data boundary

Customer data (collections, queries, documents) lives in Dataplane. The Customer Portal and federated apps access it through the Control Plane Data Vault proxy (/v1/workspaces/{id}/vault/…), never by calling Dataplane directly.

Environments

Each workspace can have multiple environments. Environment promotion (moving releases between dev → staging → prod) is pillar #10 — currently blocked on external namespace pool spec.

Next steps

Architecture — component diagram and data flows
Control Plane overview — backend pillars and services
Shell bootstrap — wire a federated app to a workspace