​

Scoped Access

Scoped access lets admins assign specific forms to editors and viewers, restricting their dashboard to only the forms they need.

​

Overview

​

How It Works

​

Two Access Systems

​

Role Resolution

1. Queries user_form_access by user_profile_id (admin grants)
2. Queries program_members by user_id and email (team invitations)
3. Merges results — higher role wins (owner > editor > viewer)
4. Applies global role overrides (global viewer caps to read-only)

// lib/form-scope.ts — simplified
const combined = [
  ...programMemberRows,   // legacy team grants
  ...userFormAccessRows,   // admin-managed grants
];

for (const row of combined) {
  const effective = applyGlobalRoleOverride(row.role, globalRole);
  rolesByFormId[row.form_id] = pickHigherRole(rolesByFormId[row.form_id], effective);
}

​

Global Role Overrides

​

Database Schema

​

user_form_access

CREATE TABLE user_form_access (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_profile_id UUID NOT NULL REFERENCES user_profiles(id) ON DELETE CASCADE,
  form_id UUID NOT NULL REFERENCES forms(id) ON DELETE CASCADE,
  role TEXT NOT NULL DEFAULT 'viewer',
  granted_by TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  UNIQUE(user_profile_id, form_id)
);

• References user_profiles(id) — a stable UUID PK — instead of auth.users, avoiding FK issues with WorkOS user IDs
• Uses TEXT for role instead of an enum, avoiding program_role type compatibility issues across deployments
• granted_by stores the admin’s user ID for audit purposes

​

Server Actions

​

getUserScopedAccess

// app/actions/system.ts
const result = await getUserScopedAccess(userId);
// → { forms, workspaces, selectedFormIds }

​

updateUserScopedAccess

// app/actions/system.ts
await updateUserScopedAccess(userId, ["form-id-1", "form-id-2"]);

1. Looks up user_profiles.id by user_id
2. Deletes all existing user_form_access rows for that profile
3. Inserts new rows for each selected form

​

UI

• See all available forms grouped by workspace
• Toggle individual forms on/off
• Save assignments with a single click