Data-Manager User and Grant Management Policy

Purpose

Data-managers may create users and manage grants within their own scope, without requiring admin or project-PI intervention. What they may grant depends on the project's kind:

• Site projects (today's rule, unchanged): coder, coding_tester and data_manager grants at their own project or project-site scope.
• District (organizational) projects (decision 2026-10-02): other data managers strictly below their own level, and interviewer, coder, reviewer, coding-tester and viewer grants at any level of their subtree.

This policy governs the /data-management/users page and its supporting API endpoints. The rule for who creates which grants is in Access Control Model, "Who creates which grants". Every write on this page asks authz.can_grant (digitva-0wc stage 6); the page offers only the roles below, so site_pi, interview_supervisor, project_pi and admin grants stay on the admin panel for everyone.

Route Family

All routes live under the existing data_management blueprint:

Route	Method	Purpose
/data-management/users	GET	User + grant management page
/data-management/api/bootstrap	GET	CSRF token and scope context
/data-management/api/projects	GET	Accessible projects
/data-management/api/project-sites	GET	Accessible project-sites
/data-management/api/organization	GET	Unit and cadre pickers for a district project: the units the caller may grant on, the project's cadres and level-cadre grid
/data-management/api/users	GET	User search
/data-management/api/users	POST	Create user
/data-management/api/access-grants	GET	List the grants the data-manager may manage (see "Visibility")
/data-management/api/access-grants	POST	Create or reactivate a grant the data-manager may create
/data-management/api/access-grants/<id>/toggle	POST	Activate/deactivate a grant the data-manager may manage

Eligible Roles

These routes accept:

• data_manager — scoped by their own grant
• in a district project, the In-charge (site_pi at a unit) and the project_pi, who pass the data-manager role gate there (authz.effective_roles) and write grants under their own rules in Access Control Model, "Who creates which grants"
• admin — any scope, within the roles this page writes

Scope Rules

A data-manager's own grants determine what they can assign.

Site projects

Today's rule, unchanged.

Project-scoped data-manager

May assign grants at:

• project level — for any project where they hold a project-scoped data-manager grant
• project-site level — for any site within those projects

Site-scoped data-manager

May assign grants at:

• project-site level only — and only for the specific project-site pairs where they hold a site-scoped data-manager grant

A site-scoped data-manager may not assign project-level grants, even for the project that contains their site.

Assignable roles (site projects)

Data-managers may only assign:

• coder
• coding_tester
• data_manager

Data-managers may not assign admin, project_pi, site_pi, reviewer, collaborator, collaborator_pii or interviewer.

District (organizational) projects

Decision 2026-10-02, implemented in digitva-0wc stage 6.

Each grant has a subtree: a project grant covers the whole project, a project_site grant its (project, site) pair, an org_unit grant its unit and every unit beneath it. One rule applies to every data manager of a district project, whatever the scope of their grant:

• data_manager grants only strictly below their own grant, inside their subtree;
• interviewer, death_reporter, coder, reviewer, coding_tester, collaborator and collaborator_pii grants at any level inside their subtree, their own level included (death_reporter at unit scope only).

So a project-scoped data-manager assigns data_manager at project-site or any unit level but never at project level; a unit-scoped data-manager assigns data_manager only on units beneath their own unit; a site-scoped data-manager assigns no data_manager grant, since nothing lies below a project-site grant. Never on a unit above or outside their own.

Data-managers may not assign admin, project_pi, site_pi, interview_supervisor or In-charge grants.

Cadre validation applies to every unit grant, and the mentor guard applies when the grantee is a mentoring institute member (see Organization Model Policy, "Unit-scoped grants" and "Mentoring institutes").

Admin

Admins bypass all scope restrictions. They can assign the roles this page writes at any project, site or unit through this interface; other roles go through the admin panel.

Grant Lifecycle

Creation

When a data-manager creates a grant:

1. The target user must be active.
2. The role must be assignable for the project's kind (see "Scope Rules").
3. The scope must fall within the data-manager's own scope; in a district project, for data_manager, strictly below their own grant.
4. If an inactive grant with the same user + role + scope already exists, it must be reactivated rather than creating a duplicate.
5. The grant status must be set to active.

Toggle (activate / deactivate)

A data-manager may toggle grants that:

• they could create under "Scope Rules" (role and scope both)
• are not the current user's own data_manager grant

A data-manager may not toggle grants with other roles or grants outside their scope. They also may not revoke their own data_manager grant through this interface.

User Creation

A data-manager may create new users. Created users:

• receive status active
• provide email and matching email_confirm, or a unique 10-digit mobile number and no email (mobile-sign-in.md)
• never get an operator-entered password: every password is generated (account-onboarding-and-passwords.md)
• with an email, receive a verification email only; pressing "Verify my email" on its link emails them a generated password
• without an email, get a one-time sign-in code shown to the creator once
• first login shows a terms-and-conditions-only gate
• start with pw_reset_t_and_c=False so onboarding gate remains in effect
• must have at least one VA language selected
• receive landing_page="coder" by default

Creating a user through this interface also requires an initial grant payload:

• project selection first (project must be in DM-manageable scope)
• role and scope: any the DM may assign under "Scope Rules" (site projects: project_site for site-scoped DMs, project_site or project for project-scoped DMs)
• target project, site or unit must be inside the DM's own scope

Visibility

Grant listing

A data-manager lists the grants they may manage under "Scope Rules", within their own scope:

• site projects: coder, coding_tester and data_manager grants
• district projects: grants of interviewer, death_reporter, coder, reviewer, coding_tester, collaborator and collaborator_pii anywhere inside their subtree, and data_manager grants strictly below their own (for an In-charge, at their own level too)
• never their own data_manager grant, which they may not revoke

They do not see admin, project_pi, site_pi, interview_supervisor or In-charge grants, nor any grant outside their scope.

From the user-details modal, a Manage Grants action navigates to the grants tab and pre-applies the selected user's email as the grants-table text filter. It also preselects that user in the new-grant form.

User listing

Data-managers may search users (up to 25 results) and open per-user details. Who they find depends on their grants:

• a project or project-site writer (data_manager at project or site scope, project_pi) and an admin search every account, as before;
• a unit writer (a data_manager at a unit, an In-charge) finds and opens only the holders of grants it may manage and the staff of mentoring institutes attached to districts it covers, with no contact details.

Find by exact email or mobile, then add (digitva-i0zb). A unit writer who needs to grant someone with an existing account outside its area types that person's full email address or full mobile number (field staff such as ANM and ASHA often have no email of their own). The lookup matches the whole value (email case-insensitive; mobile compared on digits only), no partial match, no wildcard, among active accounts. An email returns at most one person; a mobile number can return a few, since numbers are not unique. Each match shows the person's name, email, status, job title (digitva-04u4, once it exists) and their current posts: each unit where they hold an active grant with the cadre held there (for example "ANM, Sub-centre Rampur"), so the writer can confirm it has the right person. It shows no phone, no roles and no site-project grants. A miss says "No account found; create one" and offers the create-user form with the typed value filled in. A match offers "Add grant", which opens the new-grant form with that person preselected; the grant itself is decided by the normal rules (can_grant, cadre, mentor guard). Finding a person by exact email does not let the writer open their details panel or see their grants until it has given them a grant it may manage. The lookup is rate-limited, since it says whether an address has an account.

The details panel includes:

• account status (active / deactive)
• email verification status
• user VA language list
• in-scope active grant breakdown by:
  • project-level grants
  • project-site-level grants
  • unit-level grants (organizational projects)
• resend verification action (for unverified users)
• email update action only for users created by the same data-manager
• language update action for data-managers/admins
• a Manage Grants action that opens the grants tab focused on that user

CSRF

All mutating endpoints require a valid CSRF token in the X-CSRFToken header, consistent with the application-wide CSRF policy.

Audit Expectations

Grant creation and toggle operations should be auditable through the existing grant record timestamps (grant_created_at, grant_updated_at) and the notes field.

Separation from Admin Panel

This interface is intentionally separate from the /admin/ panel:

• Data-managers access it through their own dashboard at /data-management/users
• The "Manage Users" button on the data-manager dashboard links to this page
• Admins may also access this interface, but they already have the full admin panel available

The admin panel retains its own user and grant management with full role-assignment capabilities.