Managing Users

Complete guide to user management in the CRM Dashboard.

Overview

As an administrator, you can:

  • Create new user accounts
  • Edit user information and roles
  • Delete users
  • Assign users to organizations
  • Manage access permissions
  • View user activity

Accessing User Management

  1. Log in as an administrator
  2. Click Admin in the navigation (⚙️ icon)
  3. View the users table on the admin dashboard

Or navigate directly to: https://pathfinder.rangelab.io/admin

User Roles Explained

Admin

Full System Access

  • Manage all users
  • View all data across organizations
  • Access admin dashboard
  • Configure system settings
  • Create/delete users
  • Assign roles

Use Case: System administrators, IT staff

Staff

Full CRM Access

  • View all clients system-wide
  • Create and manage referrals
  • Access all resources
  • Cannot manage users
  • Cannot access admin functions

Use Case: Program coordinators, supervisors

Caseworker

Organization-Scoped Access

  • View only clients in their organization
  • Create referrals for their clients
  • Search resources
  • Limited to assigned organization

Use Case: Front-line caseworkers, intake specialists

Org Admin

Organization Administrator

  • Manage organization's resources
  • View organization's referrals
  • Coordinate with caseworkers
  • Cannot access other organizations
  • Cannot manage users

Use Case: Agency directors, program managers

Landlord

Landlord Portal Only

  • Access landlord portal
  • Manage properties and units
  • View applications
  • Track payments
  • Cannot access CRM features

Use Case: Property owners, property managers

Creating New Users

Step-by-Step Process

1. Navigate to Add User

  • From Admin Dashboard, click "Add User" button
  • Or go to /admin/users/new

2. Enter Account Information

Email Address (Required)

  • Must be unique
  • Used for login
  • Cannot be changed later

Password (Required)

  • Minimum 8 characters
  • Include letters and numbers
  • User can change after first login

Auto-Confirm User (Checkbox)

  • ✅ Checked: User can login immediately
  • ☐ Unchecked: User must verify email first
  • Recommendation: Check for internal users

3. Enter Profile Information

First Name (Required)

  • User's first name

Last Name (Required)

  • User's last name

4. Select Role (Required)

  • Choose from dropdown:
    • Admin
    • Staff
    • Caseworker
    • Org Admin
    • Landlord

5. Assign to Organization/Landlord

If Role is Caseworker or Org Admin:

  • Organization field appears
  • Select from dropdown
  • Required for these roles
  • Determines what data they can access

If Role is Landlord:

  • Landlord field appears
  • Select from dropdown
  • Required for landlord role
  • Links to their properties

If Role is Admin or Staff:

  • No assignment needed
  • They have system-wide access

6. Review and Submit

  • Verify all information
  • Click "Create User"
  • Success message appears
  • User added to users table

Example: Creating a Caseworker

Email: jane.doe@agency.org
Password: SecurePass123
Auto-Confirm: ✅ Checked

First Name: Jane
Last Name: Doe

Role: Caseworker
Organization: Portland Housing Services

Result: Jane can now login and see clients assigned to Portland Housing Services.

Example: Creating a Landlord

Email: john@propertymanagement.com
Password: SafePass456
Auto-Confirm: ✅ Checked

First Name: John
Last Name: Smith

Role: Landlord
Landlord: Smith Property Management

Result: John can login to landlord portal and manage his properties.

Editing Users

When to Edit Users

  • Role change (promotion, reassignment)
  • Organization change (transfer)
  • Name correction
  • Updating assignments

How to Edit

1. Find the User

  • Scroll through users table
  • Or use browser search (Ctrl/Cmd + F)

2. Click "Edit" Link

  • In the Actions column
  • Or navigate to /admin/users/[id]/edit

3. Modify Information

Can Change:

  • ✅ First Name
  • ✅ Last Name
  • ✅ Role
  • ✅ Organization assignment
  • ✅ Landlord assignment
  • ✅ Email address (synced to auth and normalized to lowercase)
  • ✅ Password (set/reset directly from edit panel)

4. Role-Specific Changes

Changing TO Caseworker or Org Admin:

  • Organization field becomes required
  • Select organization from dropdown

Changing TO Landlord:

  • Landlord field becomes required
  • Select landlord from dropdown

Changing TO Admin or Staff:

  • Organization/Landlord fields hidden
  • Previous assignments cleared automatically

5. Save Changes

  • Click "Save Changes"
  • User updated immediately
  • Changes take effect on next login

Common Edit Scenarios

Promoting Caseworker to Admin:

  1. Edit user
  2. Change role to "Admin"
  3. Organization assignment automatically cleared
  4. Save changes

Transferring Between Organizations:

  1. Edit caseworker
  2. Change organization dropdown
  3. Save changes
  4. User now sees new organization's clients

Converting User to Landlord:

  1. Edit user
  2. Change role to "Landlord"
  3. Select landlord from dropdown
  4. Save changes
  5. User redirected to landlord portal on next login

Deleting Users

⚠️ Important Warnings

Deletion is Permanent!

  • Cannot be undone
  • Removes authentication credentials
  • Deletes profile and associated data
  • All system access revoked

Before Deleting:

  • Reassign their clients to another caseworker
  • Document reason for removal
  • Notify the user (if appropriate)
  • Consider deactivation instead (future feature)

How to Delete

1. Find the User

  • Locate in users table

2. Click "Delete" Link

  • In Actions column
  • Or navigate to /admin/users/[id]/delete

3. Review Confirmation Page

Shows:

  • User's full details
  • What will be deleted:
    • Authentication credentials
    • Profile information
    • All system access
    • Associated data

4. Confirm Deletion

  • Read warning message
  • Click "Delete User"
  • Or click "Cancel" to abort

5. Verification

  • Success message appears
  • User removed from table
  • User cannot login anymore

When to Delete Users

Appropriate Reasons:

  • Employee terminated
  • Volunteer no longer active
  • Account created in error
  • Security concern (account compromised)
  • User requested account closure

NOT Appropriate:

  • Temporary leave (they'll return)
  • Inactive but might return
  • Just to test delete function

User Table Features

Viewing Users

Columns Displayed:

  • Name/Email
  • Role (with color-coded badge)
  • Organization/Landlord
  • Created Date
  • Actions (Edit/Delete)

Color-Coded Role Badges:

  • 🔴 Red: Admin
  • 🟣 Purple: Org Admin
  • 🟠 Orange: Landlord
  • 🔵 Blue: Caseworker
  • ⚪ Gray: Staff

Filtering Users

By Role:

  • Dropdown filter at top of table
  • Select specific role
  • Click "Filter"
  • Table updates to show only that role

Reset Filter:

  • Select "All Roles"
  • Click "Filter"

Sorting Users

Currently supported:

  • By created date (newest first)

Future enhancements:

  • Sort by name
  • Sort by organization
  • Sort by last login

Environment Variables Required

Service Role Key

To manage users, you need the Supabase Service Role Key:

Add to .env.local:

SUPABASE_SERVICE_ROLE_KEY=your-service-role-key-here

Where to Find It:

  1. Go to Supabase Dashboard
  2. Click Settings → API
  3. Copy "service_role" key (NOT anon key)

⚠️ Security Warning:

  • This key bypasses Row Level Security
  • Has full database access
  • NEVER commit to git
  • NEVER expose in client-side code
  • Keep secret at all times

Troubleshooting

"Permission denied" when creating user

Cause: Service role key not set or incorrect Solution:

  • Check SUPABASE_SERVICE_ROLE_KEY in .env.local
  • Verify it's the service_role key (not anon)
  • Restart dev server after adding

User created but can't login

Cause: Email not confirmed OR wrong role set Solution:

  • Check "Auto-confirm user" was checked
  • Verify email in auth.users table (Supabase)
  • Check profile has correct role
  • Check user is using correct email/password

Organization dropdown is empty

Cause: No organizations in database Solution:

  • Add organizations first
  • Or contact admin to create organizations

Landlord dropdown is empty

Cause: No landlords in database Solution:

  • Add landlords to database first
  • Navigate to properties section
  • Create landlord records

Can't delete user - error appears

Cause: Database foreign key constraints Solution:

  • Check if user has associated data
  • Reassign data first
  • Try again

Best Practices

Security

  1. ✅ Use strong passwords
  2. ✅ Check auto-confirm for internal users only
  3. ✅ Review user list regularly
  4. ✅ Remove terminated users promptly
  5. ✅ Use principle of least privilege (lowest role needed)
  6. ✅ Document user management actions

Organization

  1. ✅ Use consistent naming (First Last)
  2. ✅ Use work emails, not personal
  3. ✅ Assign correct organization immediately
  4. ✅ Test new accounts after creation
  5. ✅ Keep users list current
  6. ✅ Audit user roles quarterly

Communication

  1. ✅ Notify users when accounts created
  2. ✅ Provide login instructions
  3. ✅ Share initial password securely
  4. ✅ Instruct to change password on first login
  5. ✅ Explain their role and permissions
  6. ✅ Provide training resources

Quick Reference

User Creation Checklist

  • [ ] Email address (unique)
  • [ ] Strong password
  • [ ] Auto-confirm checked (if appropriate)
  • [ ] First and last name
  • [ ] Role selected
  • [ ] Organization/landlord assigned (if required)
  • [ ] User notified of new account
  • [ ] Login tested

Common Tasks

| Task | Location | Access Level | |------|----------|--------------| | Create User | Admin → Add User | Admin only | | Edit User | Admin → Edit link | Admin + Org Admin (org-scoped, staff/caseworker/viewer only) | | Delete User | Admin → Delete link | Admin + Org Admin (org-scoped, staff/caseworker/viewer only) | | View Users | Admin Dashboard | Admin + Org Admin (org-scoped list) | | Filter Users | Admin → Role dropdown | Admin + Org Admin (org-scoped list) |

Next Steps

Need help? Contact your system administrator or check the troubleshooting section above.