IdPlane Integration

How Control Plane authenticates Customer Portal and API users via IdPlane at auth.groundfloor.cloud.

IdPlane is Groundfloor's authentication service (auth.groundfloor.cloud). Control Plane uses it for the Customer Portal (app.groundfloor.cloud) and Operator Admin (admin.groundfloor.cloud). Every authenticated /v1/* request carries a Bearer JWT issued by IdPlane.

This page covers Control Plane auth — signing into Groundfloor's own portals and APIs. Optional per-workspace site auth is a separate feature; see Workspace site auth.

Flow

User → IdPlane (auth.groundfloor.cloud) → access_token (JWT)
     → Customer Portal or API client
     → Authorization: Bearer <token>
     → Control Plane verifies iss + signature
     → sub resolved to internal users.id
     → SpiceDB CheckPermission for the requested action

Principal model

After JWT verification, handlers receive a Principal with:

Field	Source	Usage
`subject_id`	JWT `sub`	Stable IdPlane user ID
`email`	JWT claim	Display, membership lookup
`scopes`	JWT	Optional fine-grained claims

Control Plane maps sub → internal users.id on each request. Authorization always uses the internal user ID when writing SpiceDB relationships.

Environments

Surface	Production	Development
IdPlane	`https://auth.groundfloor.cloud`	Shared or local IdPlane
Customer Portal	`app.groundfloor.cloud`	`localhost:3000`
Control Plane API	`platform.groundfloor.cloud`	`localhost:8088`

Tenant provisioning

In production, customers typically do not self-serve account creation. Groundfloor operators provision accounts with an owner email unless customer self-serve is enabled for the cell.

On create, Control Plane:

Creates or attaches the IdPlane user
Upserts the Portal users row
Grants owner membership on the new account

One human may belong to multiple accounts (same sub, multiple memberships).

API authentication

See API Authentication for headers, error codes, and curl examples. Obtain tokens with gf login or an OIDC client against IdPlane — see Developers.

ReBAC model — permissions after authentication
Core concepts — identity planes
Shell authentication — JWT in federated apps