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 (optional product packaging — Shell / standalone)
├── Coderunner (function / job / schedule / service)
├── Managed database, secrets, flags, files, vault
└── …| Resource | Identifier | Scope |
|---|---|---|
| Account | UUID | Billing, membership, offboarding |
| Workspace | UUID | Data, secrets, files, apps, coderunners — your tenant boundary |
| Environment | slug | Promotion target (dev → staging → prod) |
| App | slug | Optional product packaging (Shell federated or standalone) |
| Coderunner | id / slug | Deployable workload (does not require an App) |
Membership and roles
A human user (sub from IdPlane) can belong to multiple accounts. Within each account, they hold a platform membership with a role:
| Role | Typical permissions |
|---|---|
owner | Full account administration |
admin | Manage workspaces, members, most pillars |
writer | Read/write on assigned workspaces |
member | Read on assigned scopes |
partner | Read-only external collaborator |
billing_admin | Account billing (account scope) |
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.
Environment deployer is an additional platform relation for deploy targets. App end-user roles under workspace site auth are a separate plane — see Authentication and ReBAC model.
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 IdPlane 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. Use Environment Promotion to move secrets, feature flags, Shell app releases, and coderunners from dev → staging → prod. Customer vault data is not copied; public URL rewrite remains deferred.
Next steps
- Architecture — component diagram and data flows
- Control Plane overview — backend pillars and services
- Shell bootstrap — wire a federated app to a workspace