Skip to main content

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:

  1. Parses it against the live API schema
  2. Splits it into per-service queries
  3. Fetches from each services in parallel
  4. 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 calling
  • x-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 doingYou think about
Calling the GraphQL APIJust call it. The gateway handles tenant + auth.
Writing a new service moduleAdd @rbac on each field, filter by tenant_id in your resolver
Adding a new tenant to your orgDone in tenant admin — federation handles the rest
Sharing across tenantsUse guest membership — never bypass tenant filters

Next steps​