Skip to main content

​
Multi-Tenancy

Terra supports multiple organizations through a flexible folder/agency model.

​
Organization Structure

​
Folders (Workspaces)

Folders provide logical grouping with:
  • Custom branding (logo, colors)
  • Custom domain
  • Team access control
  • Shared settings
CREATE TABLE folders (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  slug TEXT UNIQUE,
  custom_domain TEXT,
  branding JSONB DEFAULT '{}'
);

​
Custom Domains

Domains are resolved in middleware: 
// src/middleware.ts
const host = request.headers.get("host");
const folder = await getFolderByDomain(host);

if (folder) {
  // Rewrite to folder context
  return NextResponse.rewrite(
    new URL(`/workspace/${folder.id}${pathname}`, request.url)
  );
}
Domain hierarchy:
  1. Form-level domain (highest priority)
  2. Folder-level domain
  3. App domain (fallback)

​
Agencies

Agencies are external partners managing multiple clients: 
CREATE TABLE agencies (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL
);

CREATE TABLE agency_clients (
  agency_id UUID REFERENCES agencies(id),
  folder_id UUID REFERENCES folders(id)
);
This enables a single partner to manage forms across multiple programs.

Authorization

Permission model

Custom Domains

DNS configuration