Tenant Setup

GTM Clarity is a multi-tenant platform where each tenant maps to a Clerk organization. Every piece of data -- accounts, people, scores, connectors -- is scoped to a single tenant to guarantee complete data isolation.

How Tenants Work

A tenant is the root isolation boundary. When a Clerk organization is created and linked, GTM Clarity provisions a corresponding row in the tenants table:

Column	Type	Description
id	text (UUID)	Internal primary key
clerk_org_id	text	Clerk organization ID (unique index)
name	text	Display name
slug	text	URL-safe identifier
settings	jsonb	Tenant-level configuration overrides
created_at	timestamptz	Creation timestamp
updated_at	timestamptz	Last modification timestamp

Isolation Model

Every table in the database includes a tenant_id column. Every query filters by tenant_id -- there is no mechanism for cross-tenant data access. This is enforced by convention through the tenantColumns base helper used in all schema definitions.

Creating a Tenant

Step 1: Create a Clerk Organization

Tenants are created through the Clerk dashboard or via the Clerk API. Each Clerk organization becomes one GTM Clarity tenant.

1. Navigate to the Clerk Dashboard
2. Go to Organizations and click Create Organization
3. Enter the organization name and slug
4. Save -- the clerk_org_id is generated automatically

Step 2: Automatic Provisioning

When a user first signs into GTM Clarity under the new organization, the platform automatically:

1. Detects the clerk_org_id from the session
2. Creates a tenants row if one does not already exist
3. Associates the user with the tenant

No manual database intervention is required.

Step 3: Initial Configuration

After tenant creation, an admin should complete the following checklist:

Task	Where	Required
Set up scoring configuration	Settings > Scoring	Yes
Connect at least one data source	Settings > Connectors	Yes
Configure ICP profile	Settings > Scoring > Fit	Yes
Set engagement decay parameters	Settings > Scoring > Engagement	Recommended
Invite team members	Settings > Team	Recommended
Configure field mappings	Settings > Connectors > Mappings	Optional
Set up buying group role templates	Settings > Buying Groups	Optional

Inviting Users

Users are invited through the Clerk organization management interface:

1. Go to Settings > Team in the GTM Clarity dashboard
2. Click Invite Member
3. Enter the email address and select a role (admin, manager, or viewer)
4. The user receives an email invitation

tip

New users automatically inherit the tenant context from their Clerk organization membership. No additional tenant configuration is needed per user.

Tenant Settings

The settings JSONB column on the tenants table stores tenant-level overrides. These are merged with system defaults at runtime:

{
  "timezone": "America/New_York",
  "defaultScoringVersion": 1,
  "features": {
    "buyingGroups": true,
    "writeback": false
  }
}

Multi-Tenant Data Flow

warning

Never bypass the tenant filter in queries. All database access must include a WHERE tenant_id = ? clause. The base schema helpers (tenantColumns) exist specifically to enforce this pattern.

Related Pages

• RBAC & Roles -- Role assignments within a tenant
• Scoring Configuration -- Per-tenant scoring setup
• Environment Setup -- Infrastructure prerequisites
• Database Schema -- Full schema reference