Managing Users

Admin Only

User management requires the Admin role.

User management controls who has access to Heelr and what they can do. Admins can create user accounts, assign roles, send invitations, and manage access.

Overview

From the User Management page, admins can:

• Create new users with a name, email, and role
• Send magic link invitations so users can securely access the system
• Assign and change roles to control permissions
• Activate or deactivate users to manage access
• Search and filter the user list

Roles

Every user is assigned one of three roles, each with progressively increasing permissions:

Role	Description
Volunteer	Entry-level access. Can view Level 1 dogs and log activities. Read-only for most features. Volunteers with Special Handling Certification can also access Special Handling dogs.
Staff	Shelter staff. Can add/edit dogs, upload photos, manage notes, and handle all dogs including isolation and PPE.
Admin	Full control. Everything staff can do, plus user management, audit logs, and all administrative features.

See Permissions for a detailed breakdown of what each role can do.

User Statuses

Each user has a status that indicates their current state in the system:

Status	Badge Color	Meaning
Active	Green	User has logged in and can access the system
Pending	Blue	User has been invited but hasn't logged in yet
Manual	Gray	User was created without system access (manual entry for tracking purposes)
Inactive	Red	User has been deactivated by an admin and cannot access the system

The User Management Page

The user management page is accessible from the navigation menu (admin only). It includes:

• Search bar -- Find users by name
• Status filter -- Filter by All, Active, Pending, Inactive, or Manual
• "Add User" button -- Create a new user
• User cards -- Each showing name, email, role badge, status badge, and an edit button
• "View Audit Logs" link -- Navigate to the audit log for user-related actions

Adding a User

To add a new user:

1. Click "Add User" on the User Management page
2. Enter the user's name (required)
3. Optionally enter their email address
4. Select a role (Volunteer, Staff, or Admin)
   • For Volunteers, optionally toggle Special Handling Certified to grant access to Special Handling dogs
5. If an email was provided, check "Send Invite" to send a magic link
6. Click Create

If you send an invite, the user's status will be set to Pending until they click the magic link and log in for the first time. If no email is provided, the user is created with Manual status.

Editing a User

To edit an existing user, click the Edit button on their user card. You can change:

• Name
• Email (see below for details on email changes)
• Role
• Active/Inactive toggle -- Deactivating a user prevents them from logging in

For users with Manual status who now have an email, you can send them a magic link invitation to grant system access.

Changing a User's Email

How email changes work depends on whether the user has logged in:

Users without login access (Manual or invited but not yet logged in)

For users who haven't logged in yet, admins can edit their email directly from the edit modal. This is a simple correction -- no approval is needed because the email isn't tied to an active login identity.

Users with login access (Active users who have logged in)

For users who have an active login, email changes go through a staged approval workflow to prevent login identity from being silently reassigned:

1. Admin requests -- Enter the new email in the edit modal and click Request Email Change. You can optionally include a reason.
2. User is notified -- The user receives a security alert email at their current address and sees a notification in the app.
3. User approves -- The user reviews the request on their profile page and approves it by entering their current password.
4. Verification -- Supabase Auth sends a verification email to the new address. The user must click the link to confirm.
5. Email updated -- Once verified, the login email is updated automatically.

The user can reject the request at any time, and admins can cancel a pending request from the edit modal. Both actions revoke any pending verification link.

tip

If you see "Pending Email Change" in the edit modal, a request is already in progress. You can cancel it and submit a new one if the details need to change.

Magic Link Invitations

Instead of creating passwords, Heelr uses magic links -- secure one-time login links sent via email. When a user clicks the link, they're automatically logged in and their status changes from Pending to Active.

You can resend invitations if a user hasn't received or has lost their original link.

Rate Limiting

To prevent abuse of the invitation system, there is a limit of 3 invitations per user within a 24-hour period. If you reach this limit, wait 24 hours before sending another invite to that user.

Audit Trail

All user management actions are logged in the audit system, including:

• User creation
• Role changes
• Activations and deactivations
• Invitation sends
• Email change requests, approvals, rejections, and cancellations

Admins can review these events from the Audit Logs page.