Users Module Recipe

The Users module is a ready-made admin surface for the three interdependent access-control domains of your DaaS backend — users, roles, and policies. Instead of hand-building user tables, role assignment, policy attachment, and a permissions matrix, you scaffold the whole thing with one command and own the code.

It gives you six screens:

• UsersManager — the /users list: search, role/status filters, pagination, status badges, and permission-gated create/edit/delete.
• UserDetail — the /users/[id] page: profile fields, password rules, role assignment (M2M), status, a static API token field (generate → plaintext shown once with Copy, saved tokens display “Value Securely Saved”, Clear revokes), plus a Policies tab for direct policy attachment.
• RolesManager — the /roles list with member counts.
• RoleDetail — the /roles/[id] page: icon, parent role (hierarchy), scope-assignment rules (regex allow-list), plus Users (membership management, move/remove in bulk) and Policies tabs. The sidebar links the role hierarchy — parent role and child roles navigate via onRoleClick.
• PoliciesManager — the /policies list with user/role attachment counts.
• PolicyDetail — the /policies/[id] page: access flags (app_access, admin_access, delegate_access) and the per-collection permissions matrix (create/read/update/delete/share), powered by the system-permissions interface — including a custom permission editor (item filters, field access, validation, presets) behind each toggle’s “Use Custom” option.

The pieces

Install

buildpad add users-routes

buildpad add api-routes

The routes

Seven files give you the whole module. They live under the (authenticated) route group, so they render inside the App Shell:

app/[lang]/(authenticated)/
├── users/
│   ├── page.tsx            # /users              — the UsersManager list
│   └── [id]/page.tsx       # /users/[id]         — UserDetail (use /users/new to create)
├── roles/
│   ├── page.tsx            # /roles              — the RolesManager list
│   └── [id]/page.tsx       # /roles/[id]         — RoleDetail (use /roles/new to create)
├── policies/
│   ├── page.tsx            # /policies           — the PoliciesManager list
│   └── [id]/page.tsx       # /policies/[id]      — PolicyDetail (use /policies/new to create)
└── module-access-keys/
    └── page.tsx            # /module-access-keys — the ModuleAccessKeysManager registry

"use client";
 
import React from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { UsersManager } from '@/components/ui/users-management';
 
export default function UsersPage() {
  const router = useLocaleRouter();
 
  return (
    <UsersManager
      onUserClick={(user) => router.push(`/users/${user.id}`)}
      onCreateUser={() => router.push('/users/new')}
    />
  );
}

"use client";
 
import React, { use } from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { RoleDetail } from '@/components/ui/users-management';
 
export default function RoleDetailPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);
  const router = useLocaleRouter();
 
  return (
    <RoleDetail
      id={id}
      onBack={() => router.push('/roles')}
      onDeleted={() => router.push('/roles')}
      onSaved={(role, action) => {
        if (action === 'quit') router.push('/roles');
        else if (action === 'addNew') router.push('/roles/new');
        else if (id === 'new') router.push(`/roles/${role.id}`);
      }}
      onUserClick={(user) => router.push(`/users/${user.id}`)}
      onPolicyClick={(policy) => router.push(`/policies/${policy.id}`)}
      onRoleClick={(role) => router.push(`/roles/${role.id}`)}
    />
  );
}

"use client";
 
import React from 'react';
import { ModuleAccessKeysManager } from '@/components/ui/users-management';
 
export default function ModuleAccessKeysPage() {
  return <ModuleAccessKeysManager />;
}

The data layer

All screens are thin — the work lives in hooks you can reuse anywhere.

useUsers returns fetchUsers (page/search/role/status filters), getUser, getMe, createUser, updateUser, updateMe, deleteUser, bulkUpdateUsers (role membership across many users), and the policy attachment trio fetchUserPolicies / attachUserPolicy / detachUserPolicy:

const { fetchUsers, bulkUpdateUsers } = useUsers();
 
const { users, total } = await fetchUsers({ role: roleId, status: 'active' });
await bulkUpdateUsers(users.map(u => u.id), { addRoles: [editorRoleId] });

useRoles mirrors it for roles (fetchRoles with includeUsers counts, getRole with includePolicies, getMyRoles, CRUD, and fetchRolePolicies / attachRolePolicy / detachRolePolicy). usePolicies covers policy CRUD (list rows include userCount / roleCount), and useAccess exposes the raw daas_access junction for advanced flows.

fetchUsers and fetchPolicies accept a Directus-style sort param ('email' / '-email') — that’s what the sortable list headers drive. bulkUpdateUsers covers role membership only; the managers’ bulk status and bulk delete fan out through updateUser / deleteUser per selected user.

Custom permission rules

Beyond the matrix’s All / None toggles, each cell’s menu has Use Custom, which opens a tabbed editor for that collection/action pair. The tabs depend on the action (matching Directus semantics):

Filter and validation rules use standard Directus filter syntax and support the dynamic variables $CURRENT_USER, $CURRENT_ROLE, $CURRENT_ROLES, $CURRENT_POLICIES, $NOW, and $CURRENT_RESOURCE_URI:

{
  "_and": [
    { "status": { "_eq": "published" } },
    { "user_created": { "_eq": "$CURRENT_USER" } }
  ]
}

Edits stay local to the matrix’s dirty state — like the All/None toggles, they are applied to /api/permissions only when the admin hits Save on the policy. Filters using _has, dot-notation, or _some/_none show a warning: relational rules fall back to a two-step query on child mutations.

Cells required by App Access minimal permissions render cyan and are extendable but irrevocable: their menu offers All Access and Use Custom (add item filters, validation, or presets on top of the minimum) but never No Access, and the enforced minimal fields stay checked and locked in the editor. The field lists come from app/api/fields/* and app/api/relations (included in api-routes).

RBAC behaviour

• Every action is gated with usePermissions().canPerform(collection, action) (admins bypass): the Add buttons, row menus, and Save/Delete buttons hide when the current user lacks the corresponding permission on daas_users, daas_roles, or daas_policies.
• Until the permissions are known, no write control is drawn and the forms take no edit: no Add button, no row menu, no selection column, a row that does not open its record, no Save or Delete button, and a covered form. The controls appear when the answer is in, so a user without a right does not see its button first. A new route does not open its form before then. Reading does not wait: the lists and the records load at once. A later refresh of the permissions (a renewed token, another scope) keeps the controls as they were until its answer is in.
• Bulk selection follows the same gates: the checkbox column only renders with update or delete permission, and within the toolbar “Update roles…” / “Set status” are update-gated while “Delete” is delete-gated. Column sorting is read functionality and is never permission-gated.
• The module is admin-oriented — gate your navigation links with usePermissions too, so non-admins never see /users.
• A user’s roles come back scope-filtered: in multi-tenant setups the daas_user_roles junction is tagged with a resource_uri, and role assignments cascade to child scopes.
• Invitations are modelled with status: 'invited' — there is no separate invite endpoint. Create the user with the invited status (password can be set via the reset flow later).

Prerequisites

• The module must live under your authenticated layout so DaaSProvider is above it — buildpad init generates this as app/[lang]/(authenticated)/ with a DaaSProviderWrapper.
• Deleting a user also deletes their auth account; the confirm modals make destructive actions explicit.
• No extra styling is needed: the components consume the design tokens through the Mantine theme. See the Styleguide for the token reference.

See the components live

Every surface of the Users module is in the Users Storybook. Run it locally with pnpm --filter @buildpad/ui-users storybook (port 6011). The Live DaaS stories of UsersManager, RolesManager and PoliciesManager connect to a real DaaS instance through the storybook-host proxy and include in-story list ↔ detail navigation.