Dataplane Authorization Brief

How Control Plane auth relates to Dataplane — projection scope, SpiceDB boundaries, and integration rules.

This page explains the authorization boundary between Control Plane and Dataplane. It is written for teams building on or integrating with Dataplane.

TL;DR

Layer	Data	Auth store	Projection needed?
Control Plane	Platform metadata (~10 Postgres tables)	Direct SpiceDB gRPC	No — scale is thousands of rows, not millions
Dataplane	Customer business data	SpiceDB + optional projection	Yes at scale

Rule for integrators: Federated apps and the Customer Portal call Control Plane APIs. Do not call Dataplane directly from the browser.

What Control Plane stores

Dedicated Postgres database gf_controlplane:

Table	Purpose
`users`	Portal user identity (synced from IdP)
`accounts`	Billing / org units
`workspaces`	Tenant boundaries
`environments`	dev / staging / prod
`memberships`	User → scope role grants
`audit_events`	Append-only audit (30d retention)
`provisioning_runs`	Saga state
`processed_idp_events`	Webhook idempotency

Customer collections, documents, and queries live in Dataplane — accessed through Control Plane proxies like Data Vault.

SpiceDB usage

Control Plane uses the portal_* namespace in a shared SpiceDB instance with Dataplane tenant types. Prefixing prevents schema collisions.

Operation	Path
Schema read/write	Direct authzed gRPC
`CheckPermission`	Direct authzed gRPC
`WriteRelationship`	Direct gRPC + DLQ on failure

Dataplane's /transaction rebac_write op is not in the Control Plane write path after the storage cutover.

Why Control Plane skips projection

Permission projection materializes SpiceDB tuples into customer databases so SQL queries can filter by permission at scale.

Control Plane does not need this because:

List endpoints use the memberships table as a permission proxy
Per-record checks are O(1) SpiceDB round-trips — fine for admin UI QPS
Row counts are thousands, not millions

Projection remains a customer-data feature for Dataplane tenants.

Read patterns

Endpoint style	SpiceDB on list?	Notes
`GET /v1/workspaces`	No — membership join	Shows workspaces you belong to
`GET /v1/workspaces/{id}`	Yes	Per-record `read` check
Data Vault query	Yes	Workspace-scoped proxy to Dataplane

Write patterns

Postgres transaction commits the data row
write_spicedb_or_dlq() writes the tuple after commit
DLQ drain retries failures; drift reconciler heals membership tuples hourly

Integration implications

Scope projection design to customer-tier datastores only
Do not build a Control Plane Postgres projection adapter
Use Control Plane /v1/workspaces/{id}/vault/… for customer data from apps
For ReBAC debugging on customer data, Dataplane may expose operator trace endpoints

SpiceDB schema — portal_* definitions
ReBAC model — action vocabulary
Data Vault API — customer data proxy
Shell data vault — app integration guide

Dataplane Authorization Brief

On this page