User Management

PSS Bids Manager uses an invitation-only user management system. Administrators must explicitly invite users before they can access any service.

info

This guide is for ADMIN users only. Only administrators can manage users and service access.

User Status Lifecycle

Users progress through three status states:

Status	Description	Can Login?
PENDING_INVITATION	User invited but hasn't accepted	❌ No
ACTIVE	User accepted invitation	✅ Yes
DISABLED	Access revoked (soft delete)	❌ No

Service-Specific Access

Users are granted access to specific services, not blanket platform access:

Service	Description	Typical Roles
BIDS	Bid estimation and management	ADMIN, ESTIMATOR, PM
PROJECTS	Purchase orders and cost tracking	ADMIN, PM, OPS, ACCOUNTING
FIELD	Timesheets and GPS tracking	ADMIN, FOREMAN

warning

Service access is explicit. Being invited to BIDS does not automatically grant access to PROJECTS or FIELD.

Role System

Base Role

Every user has a base role that applies by default across all services.

Per-Service Override

Optionally, a user can have a different role for specific services.

Example:

User: John Smith
Base Role: ESTIMATOR
Service Access:
  - BIDS: (uses base role → ESTIMATOR)
  - PROJECTS: PM (override)
  - FIELD: (no access)

Available Roles

Role	Description	Common Services
ADMIN	Full system access, manage users/settings	All
ESTIMATOR	Create and edit bids, full estimation	BIDS
PM	Project management, approve POs	BIDS, PROJECTS
OPS	Operations, manage projects	PROJECTS
ACCOUNTING	Review and approve POs	PROJECTS
FOREMAN	Clock crews in/out, manage timesheets	FIELD

Inviting Users

1

Navigate to Users Page

Go to Admin Panel → Personnel → Users

2

Click Invite User

Click the "Invite User" button in the top-right corner

3

Fill Invitation Form

Enter user details:

Field	Description
Email	User's email address
Name	Full name
Base Role	Default role for all services
Service Access	Select which services to grant
Service Overrides	Optionally set different roles per service

4

Send Invitation

Click "Send Invitation". System creates the user with status PENDING_INVITATION and generates an invitation link.

5

Share Invitation Link

Copy the invitation link and send to the user via email or messaging.

note

Invitation links expire after 7 days and are one-time use.

Invitation Link Format

https://forge.precisionsiteservices.com/invite?token=abc123...

User Accepts Invitation

When the invited user clicks the link:

1. Redirected to Portal with invitation details
2. Clicks "Accept Invitation"
3. Signs in with Google OAuth (email must match invitation)
4. System verifies token and activates user
5. User redirected to first available service (typically BIDS)

Managing Existing Users

Users Table

The Users page displays all system users with:

• Name and email
• Status badge (PENDING, ACTIVE, DISABLED)
• Base role
• Service access summary
• Last login timestamp
• Action buttons

Filtering and Search

Filter	Description
Search	Filter by name or email
Status	PENDING / ACTIVE / DISABLED
Role	Filter by base role
Service	Show only users with access to specific service

User Actions

Edit User

Click Edit icon to modify:

• Name
• Base role

warning

You cannot change a user's email address. Create a new invitation if needed.

Manage Services

Click Services to:

• Grant access to new services
• Revoke service access
• Set per-service role overrides

Disable User

Click Disable to prevent login:

• User status changes to DISABLED
• Cannot login (existing sessions may continue until token expires)
• User data is preserved
• Can be re-enabled later

note

You cannot disable yourself.

Delete User

Click Delete to permanently remove:

Bid Handling Options:

Option	Effect	Use Case
Transfer	All bids assigned to selected user	User leaving, work continues
Orphan	Bids remain, createdBy shows "[Deleted User]"	Historical preservation
Delete	All user's bids are deleted	Clean removal

warning

Deletion is permanent and cannot be undone. Type the user's email to confirm.

Resend Invitation

For users with PENDING_INVITATION status:

1. Find the user in the table
2. Click Actions → Resend Invitation
3. New invitation link generated (old token revoked)
4. Share the new link with the user

Self-Service Profile

All users can manage their own profile:

1. Click user menu dropdown → Profile
2. View profile information
3. Edit own name
4. View service access (read-only)
5. View recent activity log

note

Users cannot change their own role, email, or request additional service access. They must contact an administrator.

Bulk Operations

Select multiple users using checkboxes to:

• Bulk Enable - Re-activate disabled users
• Bulk Disable - Prevent login for multiple users
• Bulk Delete - Remove multiple users (with bid handling options)
• Export to CSV - Download user list

API Endpoints

Admin Endpoints

All require ADMIN role:

Method	Endpoint	Description
GET	/api/admin/users	List all users
GET	/api/admin/users/:id	Get single user
POST	/api/admin/users/invite	Invite new user
PATCH	/api/admin/users/:id	Update user
PATCH	/api/admin/users/:id/status	Enable/disable user
DELETE	/api/admin/users/:id	Delete user
POST	/api/admin/users/:id/resend-invite	Resend invitation
PUT	/api/admin/users/:id/services/:service	Grant/update service access
DELETE	/api/admin/users/:id/services/:service	Revoke service access
GET	/api/admin/users/export	Export users to CSV

Self-Service Endpoints

All authenticated users:

Method	Endpoint	Description
GET	/api/users/me	Get own profile
PATCH	/api/users/me	Update own name
GET	/api/users/me/activity	Get own audit log

Security

Invitation Tokens

• 32-character alphanumeric tokens
• Expire after 7 days
• One-time use (cleared after acceptance)
• Can be revoked by admin
• Email must match when accepting

Authorization

• SuperTokens sessions contain role and services claims in session data
• Each service validates access on protected routes
• ADMIN role bypasses service checks
• Disabled users' sessions are invalidated immediately

Audit Logging

All user management actions are logged:

• User invited, invitation accepted
• User updated, disabled, enabled, deleted
• Service access granted, revoked

Best Practices

🛡️

Principle of Least Privilege

Grant only the minimum service access and role needed for each user's job function.

📅

Regular Access Review

Periodically review user access and disable accounts for users who no longer need access.

🕐

Invitation Expiry

Resend invitations if they expire. Don't share expired links.

📚

Service Segregation

Use per-service role overrides to give users different permissions in different services.

Migration from Auto-Registration

When the invitation system was deployed:

1. All existing users were set to ACTIVE status
2. All existing users were granted BIDS service access with their current role
3. New users can no longer auto-register
4. Domain whitelist still applies to invitations (@precisionsiteservices.com)

Troubleshooting

User sees "No invitation found" error

The user is trying to login but hasn't been invited yet. Create an invitation for them.

User sees "Check email for invitation" error

User status is PENDING_INVITATION. They need to click the invitation link to accept.

User sees "Account disabled" error

User status is DISABLED. Re-enable the account via Admin Panel → Users.

Invitation link expired

Links expire after 7 days. Use "Resend Invitation" to generate a new link.

Next Steps

🔑

Role Permissions

Configure which roles can perform specific actions

📄

Audit Logs

Track all user management activities