Federation & multi-tenancy
The platform exposes a single GraphQL endpoint that secretly stitches together many services. Multi-tenancy is enforced at the edge so every services stays simple.
What you'll learn
- How federation lets us compose a unified API from many services
- How tenant context flows through every request
- What you (as a developer) never need to think about
Federation in one diagram
Client → Gateway → [tags-svc, rbac-svc, files-svc, ...]
│
Schema registry
The gateway reads a live API schema from the schema registry — a composed schema spanning all services. When a query comes in, the gateway:
- Parses it against the live API schema
- Splits it into per-service queries
- Fetches from each services in parallel
- Stitches the results back into one response
To you as an API caller, it looks like one GraphQL API. To the engineers writing service module, each service owns its own schema.
→ Developer reference: GraphQL API
Multi-tenancy at the edge
Every request that reaches a service module already has tenant context attached:
x-actor-id/x-actor-type— who's callingx-workspace-id— what workspace (workspace-layer requests only)x-tenant-id— derived from the workspace
Subgraphs never have to:
- Validate tokens
- Look up which tenant a user belongs to
- Cross-check workspace membership
The gateway does all of that before routing to services. Subgraphs just trust the headers and filter their data by tenant_id / workspace_id.
RBAC composes with federation
Every public field carries an @rbac directive declaring required permissions. The gateway enforces it by reading the directive from the live API schema. Subgraphs don't re-implement auth.
→ Admin reference: RBAC overview
What this means for you
| You're doing | You think about |
|---|---|
| Calling the GraphQL API | Just call it. The gateway handles tenant + auth. |
| Writing a new service module | Add @rbac on each field, filter by tenant_id in your resolver |
| Adding a new tenant to your org | Done in tenant admin — federation handles the rest |
| Sharing across tenants | Use guest membership — never bypass tenant filters |