Roles and access

Control who can do what in 1PVN by assigning roles. Every user belongs to one tenant (chamber) and has one role in that tenant. New users start as public (pending activation) after their first sign-in, and only admins can promote them. There is also a separate platform-admin role for cross-tenant management from the master console.

Purpose: Protect workbench data, enforce approval workflows, and delegate the right level of access to each person.

Audience: Tenant admins and platform admins.

Prerequisites: Admin role in your 1PVN tenant (for per-tenant user management), or platform-admin for cross-tenant tasks.

Overview

1PVN has six per-tenant roles in a hierarchy from least to most powerful:

Role	Numeric level	What it means
public	0	Pending activation; cannot access the workbench
lgu	1	Local government unit; limited workbench features
staff	2	Core workbench user; can create and edit data
reviewer	3	Can approve AI-generated content and approval requests
lead	4	Manager; can archive records and send campaigns
admin	5	Full control of tenant config and user management

Any action that requires a minimum role also permits all roles above it. For example, an action that requires staff (level 2) is also available to reviewer, lead, and admin.

Plus one cross-tenant role: platform-admin is separate from the per-tenant hierarchy. Platform admins manage all chambers from the master console (app.1pvn.com/console). A person can be a platform-admin without being an admin in any individual chamber.

Step-by-step: What happens on first login

When someone signs into 1PVN for the first time:

User completes sign-in (Google OAuth or email/password).
1PVN checks the tenant's staff allowlist. If the user's email domain or exact email is not on the allowlist, they see "Access restricted" and cannot proceed.
1PVN creates a user record with role = public. The account exists but is not activated.
User is redirected to /auth/pending.

On the pending page, the user sees:

The message: "Account pending activation — Your sign-in succeeded but your 1PVN account has not been activated yet."
Their signed-in email address.
The administrator contact email for your chamber (configured per deployment via NEXT_PUBLIC_ADMIN_CONTACT_EMAIL).
A Sign Out button.

The user cannot access /dashboard or any workbench feature until an admin promotes their role.

Screenshot: /auth/pending page showing amber info card, "Account pending activation" heading, user's email, and administrator contact link.

Step-by-step: Activating a user (promoting from public to staff)

Requires: Admin role in the tenant.

Go to /admin/users. The page lists all active users in your tenant. By default, archived users are not shown.
Find the user in the table. Look for their email. Their Role column shows public. Use the filter bar and select "Public" if you need to narrow down the list to pending users only.
In the "Change Role" column, open the dropdown and select the new role.
- Most new users get staff (full workbench access).
- Use reviewer for someone who approves meeting minutes or approval requests.
- Use lead for managers who archive records and send communications.
- Reserve admin for people who need to manage users and system config.
Click Update. The role change is saved immediately. The audit log records the change with the timestamp and your user ID.
Tell the user to sign out and sign back in. Their active session still shows the old role. On their next sign-in, they are redirected to /dashboard instead of /auth/pending.

Screenshot: /admin/users table with email column, Role column showing public, Change Role dropdown set to staff, and Update button.

Step-by-step: Changing an existing user's role

Same process as activating a user above — go to /admin/users, find the user, select the new role from the dropdown, and click Update.

Key restrictions:

An admin cannot change their own role. Attempting to do so returns the error: "Cannot change your own role."
Only users with the admin role can change roles. Staff, reviewers, and leads have no access to /admin/users.
Every role change is logged to the audit trail with the timestamp and the admin who made the change.

Step-by-step: Archiving a user

Requires: Admin role in the tenant. The archiveUserAction is available in the platform, but note that the /admin/users page does not currently show an archive button in the UI — this must be triggered via a server action or a custom admin tool.

When a user is archived (is_archived = true):

They cannot sign in anymore.
They disappear from the default /admin/users list (the page only shows active users).
All their records, notes, audit trail, and history are preserved. No data is deleted.

Key restriction: An admin cannot archive themselves. Attempting to do so returns the error: "Cannot archive yourself."

What each role can do

public

Can: View public pages (submit investment opportunity, register, track a submission, view event agenda, RSVP to events).
Cannot: Access /dashboard or any workbench feature.
Next step: An admin must promote this user to unlock workbench access.

lgu

Can: Limited workbench features (context-dependent per deployment).
Cannot: Full workbench operations available to staff.
Note: Defined in the role system but specific feature access depends on your chamber's configuration.

staff

Can:
- Access the full workbench (/dashboard and all workbench routes).
- Create and edit submissions, consultations, opportunities, contacts, and organizations.
- Add attendees, log notes, manage agendas.
- Upload documents and take field captures (voice notes, QR scanning).
- Submit and view forms.
- Request approvals and send for e-signature.
Cannot:
- Manage users or change roles.
- Archive organizations or consultations.
- Change system configuration.
- Access platform admin (master console).

reviewer

Can: Everything staff can, plus:
- Approve or reject AI-generated meeting notes (pending review status).
- Make decisions on approval requests (advance, return for revision).
Cannot: Manage users or change system configuration.

lead

Can: Everything reviewer can, plus:
- Archive organizations, consultations, and documents.
- Send communication campaigns to audiences.
- Send documents for e-signature.
- Override certain workflow gates.
- Cancel approval requests.
Cannot: Manage users or change system configuration.

admin

Can: Everything lead can, plus:
- Manage users: promote roles, archive accounts.
- View and query audit logs (/admin/audit).
- View system entity counts (/admin/settings).
- Configure email templates, document templates, and form definitions.
- Manage workflows and feature flags.
- Manage change requests, incidents, and feedback intake.
- Initiate GDPR data exports and erasures.
- Full access to tenant configuration.
Cannot:
- Change their own role.
- Access other tenants' data (unless they are also a platform-admin).
- Directly modify database migrations or schema.

platform-admin

Cross-tenant role — separate from per-tenant admin.
Can:
- Access the master console (/console/overview, /console/tenants, /console/admins).
- View all tenants and their metrics.
- Create new tenants (chambers).
- Manage staff email allowlists per tenant.
- Suspend or resume tenants.
- Set per-tenant logos and branding.
- Manage the platform-admin roster.
Note: Platform admins use a separate credential system. Being a platform-admin does not automatically grant admin role inside any specific tenant.

Examples

Example 1: Activating a new staff member

Ana from a partner organization signs into 1PVN for the first time using Google on Monday morning.

Ana sees the Account pending activation page. She emails the admin contact listed there.
You (admin) go to /admin/users, filter by "Public" role, find Ana's email in the list.
You select "staff" from the dropdown in the Change Role column and click Update.
You reply to Ana and tell her to sign out and back in.
Ana signs in again and is taken to /dashboard with full staff workbench access.

Example 2: Promoting a staff member to reviewer

Your program coordinator has been approving AI-generated meeting minutes manually via the notes UI, but keeps hitting "Access denied" on the approve button.

Go to /admin/users, find their email.
Change their role from "staff" to "reviewer" and click Update.
Tell them to sign out and back in.
They can now approve and reject pending meeting notes.

Example 3: Temporarily reducing someone's access

A team member is going on extended leave. You want to prevent accidental changes while they're away.

Go to /admin/users, find their email.
Change their role from "staff" to "public" and click Update.
On their next sign-in attempt, they will see the pending activation page.
When they return, change the role back to "staff" in the same way.

Best practices

Principle of least privilege. Assign the lowest role that covers the person's actual job.
- Field data entry → staff
- Second-approver or QA → reviewer
- Manager who archives and sends → lead
- Only promote to admin if someone needs to manage users or system config.
Onboarding checklist.
- New user signs in → they see /auth/pending. ✓
- You confirm their email address is correct.
- You promote them to the appropriate role (usually staff). ✓
- You tell them to sign out and sign back in.
- They confirm they can access the features they need. ✓
Audit trail. Every role change is logged. Use /admin/audit to review who changed what and when. Filter by entity users to see a history of role changes.
Avoid role creep. Do not give everyone admin access "just in case." Admins can see all user data and system configuration.
Cross-tenant access. If a person needs access to multiple chambers, they must be added to each chamber's staff allowlist and have a user record in each. Roles are independent per tenant — someone can be admin in Chamber A and staff in Chamber B.

Warnings

Cannot change your own role

Who it affects: Any user with admin role.
What happens: Trying to update your own role via /admin/users returns: "Cannot change your own role."
Why: Prevents accidental self-lockout.
Workaround: Ask another admin to change your role.

Cannot archive yourself

Who it affects: Any user with admin role.
What happens: The archiveUserAction blocks self-archiving with: "Cannot archive yourself."
Why: Prevents accidental loss of the only admin account.

Public users cannot access the workbench

Any user with role public is blocked from /dashboard and redirected to /auth/pending, regardless of how they arrived.
Setting someone's role back to public is a quick way to suspend their workbench access without archiving their account.

Email allowlist gates access before role matters

If a user's email is not on the tenant's staff allowlist (staff email domains or explicit email list), they see "Access restricted" at login and never reach the pending page. An admin or platform-admin must first add the email to the allowlist via /console/tenants.

Archived users are hidden, not deleted

Archived users do not appear in the default /admin/users list. All their records remain in the database. Data is never hard-deleted.

Troubleshooting

Symptom: New user signed in but sees "Access restricted"

Cause: The user's email is not on the tenant's staff email allowlist.
Fix: A platform-admin must go to /console/tenants, select the tenant, and add the email domain or exact email to the allowlist. The user can then sign in again.

Symptom: User was promoted to staff but still sees "Account pending activation" after signing in

Cause: The user's active session still reflects the old role. The role change applies to new sessions only.
Fix: Tell the user to sign out (using the Sign Out button on the pending page), then sign back in. Their new role takes effect immediately on re-login.

Symptom: "Cannot change your own role" error

Cause: You are submitting a role change for your own user ID.
Fix: Check the user list — you may have accidentally clicked Update on your own row. Ask another admin to change your role if needed.

Symptom: A user does not appear in the /admin/users list

Cause 1: The user's account has been archived (is_archived = true). The page only shows active users.
Cause 2: The user belongs to a different tenant. Admins only see users in their own tenant.
Fix for Cause 1: Archive management currently requires a direct server action — there is no UI to view or restore archived users on this page.

Symptom: I do not see a "Change Role" dropdown or Update button on /admin/users

Cause: You are not signed in with the admin role.
Fix: Ask your tenant admin to promote your role to admin, or contact your platform-admin.

FAQ

Q: Can someone have a different role in two different chambers? Yes. Roles are per-tenant. The same person can be admin in one chamber and staff in another. Each chamber manages its own user roles independently.

Q: Why do new users start as public? By design. 1PVN requires explicit admin activation of new accounts. This ensures a human reviews each new person before they can access workbench data.

Q: What is the difference between platform-admin and admin?

Admin is a per-tenant role. An admin can manage users and configuration within their chamber only.
Platform-admin is a cross-tenant super-role. Platform admins manage all chambers from the master console and can create new tenants, manage allowlists, and suspend chambers.

Being a platform-admin does not automatically make you an admin in any specific chamber.

Q: Can I recover an archived user's data? Yes. Archiving is a soft-delete (is_archived = true). The user's records, audit trail, and history remain in the database. Restoring an archived user currently requires a server action (no UI available).

Q: What happens to approval requests or tasks if someone's role is changed to public? Approvals and tasks already assigned to them remain assigned. If they need to act on an approval and now lack the reviewer or lead role, those actions will be blocked by the role check. Reassign the items before demoting the user if needed.

Q: Can a reviewer or lead promote users? No. Only users with the admin role can access /admin/users and change roles.

Q: Can I bulk-promote multiple users at once? No. The /admin/users page promotes one user at a time via the inline dropdown. There is no bulk role-change UI.

Q: Who is the admin contact shown on the pending activation page? The email shown is configured per deployment via the environment variable NEXT_PUBLIC_ADMIN_CONTACT_EMAIL. Set it to your chamber's operational admin address so pending users know who to contact.

Staff workbench overview
Master console overview — platform-admin role, tenants, and allowlists
System architecture overview — how multi-tenant isolation works under the hood