Authentication

IdPlane JWT authentication for Control Plane customer and workspace-scoped API calls.

All customer API endpoints require a Bearer JWT issued by IdPlane (auth.groundfloor.cloud).

Request header

Authorization: Bearer <access_token>
Content-Type: application/json

export CP_URL="https://platform.groundfloor.cloud"
export TOKEN="<idplane_access_token>"   # e.g. $(gf token)

curl -s -H "Authorization: Bearer $TOKEN" \
  "$CP_URL/v1/workspaces" | jq .

Token claims

Claim	Usage
`sub`	Stable user ID — mapped to Portal `users` row
`email`	Display and membership lookup
`iss`	Must match the configured IdPlane issuer

Control Plane resolves sub → internal user ID, then checks SpiceDB for the requested action on the target resource.

Permission model

Authorization is ReBAC, not role strings alone. Common actions:

read · write · delete · ddl · administer · manage_members · view_billing · deploy

A 403 means SpiceDB denied the action — not an invalid token.

Workspace-scoped endpoints

Routes under /v1/workspaces/{workspace_id}/… require:

Valid JWT
read / write / delete / ddl on that workspace (per endpoint)

Public endpoints

Unauthenticated, rate-limited:

Endpoint	Purpose
`GET /v1/public/tls-authorize`	ACME TLS authorization
`GET /v1/public/route`	Edge hostname → upstream routing
`GET /v1/public/workspaces/{id}/apps/by-slug`	Shell bootstrap

See Front Door and Shell bootstrap.

Local development

Surface	Typical value
IdPlane	`https://auth.groundfloor.cloud`
Control Plane API	`http://localhost:8088`

Obtain a token with gf login / gf token, or by signing in to the Customer Portal. See Developers and IdPlane integration.

Errors

Status	Meaning
401	Missing, malformed, or expired JWT
403	Valid JWT but SpiceDB denied the action