> For the complete documentation index, see [llms.txt](https://spice.docs.medtroniclabs.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://spice.docs.medtroniclabs.org/admin-guide/users-roles-and-access.md).

# Users, Roles & Access

Every person who uses SPICE, whether in the Admin Portal, the reporting applications or the mobile app, has a user account. A user's **roles** decide what they can do, and their **assignments** (a facility, villages or an area of the hierarchy) decide where they can do it.

This page explains how to create users, assign roles and sites, edit and deactivate accounts, and reset passwords. It also lists the roles you can assign.

## Who can manage users

Administrators manage users within their own area:

* Super administrators manage users anywhere.
* Region, district and sub-district administrators manage users in their part of the hierarchy.
* Facility administrators manage the users of their own facility.
* Manager-level users (area, regional or head-office) can list users across their region.

You can only assign roles that are junior to your own. Super administrators can also assign roles at their own level. The roles you can choose from are further limited to the roles enabled for your deployment.

## Roles

The names below are generic. Your deployment may rename roles or enable only some of them.

### Administrator roles (Admin Portal)

| Role                                                | Purpose                                                                         |
| --------------------------------------------------- | ------------------------------------------------------------------------------- |
| Super administrator                                 | Sets up regions, the hierarchy, workflows and databases, and manages all users. |
| Region administrator                                | Manages a region, its districts and users.                                      |
| District administrator                              | Manages a district, its sub-districts, facilities and users.                    |
| Sub-district administrator                          | Manages a sub-district, its facilities and users.                               |
| Facility administrator                              | Manages one or more facilities and their users.                                 |
| Manager roles (area, regional or head-office level) | Oversee facilities and users across a region.                                   |

See the [Admin Portal Overview](https://spice.docs.medtroniclabs.org/admin-guide/admin-guide.md) for what each administrator can do.

### Mobile app roles

Mobile roles control what a user sees and can do in the SPICE mobile app.

| Group                       | Roles                                                                                                                                                                                                                                                          |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Community-based deployments | Community health worker, community supervisor (a peer supervisor who oversees community health workers), community health assistant, community health care provider, health educator, nurse, field organiser and programme organiser (field supervision roles) |
| Facility-based deployments  | Health coach, health screener, health records officer, lab technician, nutritionist, counsellor, pharmacist, provider, nurse, physician prescriber                                                                                                             |
| Telecounselling             | Technical and non-technical telecounsellor                                                                                                                                                                                                                     |

### Reports and Insights roles

A user can also be given roles in the other suites. These roles control access to the reporting and analytics applications:

| Suite        | Roles                                               |
| ------------ | --------------------------------------------------- |
| **Reports**  | Report administrator, facility report administrator |
| **Insights** | Insights user, insights developer                   |

## Create a user

You can add users from several places. Which one you use depends on the role you are creating.

| Where                                                         | Use it for                                                  |
| ------------------------------------------------------------- | ----------------------------------------------------------- |
| **Users** page, then **Add User**                             | Users at facilities, in any role you are allowed to assign. |
| A facility summary, then **Add User**                         | Users who belong to that facility.                          |
| **Admins** page, then **Add Admin**                           | Administrator accounts at the level you are working in.     |
| The first step of creating a region, district or sub-district | The first administrator of that area.                       |
| The last step of creating a facility                          | The first user of the facility.                             |

1. Select **Add User** (or **Add Admin**).
2. Choose the **Suite Access**: **SPICE** (the Admin Portal and mobile app), **REPORTS**, **INSIGHTS**, or a combination. The suites you can choose depend on your role.
3. Choose the roles for each suite you selected: **SPICE Role**, **REPORTS Role** and **Insights Role**. You can choose more than one role in each suite for facility users.
4. Fill in the personal details.
5. Fill in the assignment fields that appear for the roles you chose.
6. To add several users in one go, select **Add Another User** (or **Add Another Admin**) and fill in the next one. Use **Remove User** to drop a row, or **Reset Fields** to clear a row.
7. Select **Submit**.

When the user is created, SPICE emails them a link to set their password. They do not receive a password from you. If they do not receive it, see [Reset a password](#reset-a-password).

### Personal details

| Field                                | Required                                   | Rules                                                                                              |
| ------------------------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| **First Name**                       | Yes                                        | 2 to 100 characters: letters, spaces, apostrophes, periods and hyphens.                            |
| **Last Name**                        | Yes                                        | 1 to 100 characters, same characters.                                                              |
| **Username**                         | Yes                                        | No spaces. Must be unique. The portal checks it when you leave the field. Cannot be changed later. |
| **Email ID**                         | Yes                                        | A valid email address, stored in lower case. Must be unique. Cannot be changed later.              |
| **Gender**                           | No                                         | Options shown depend on your deployment.                                                           |
| **Phone Number**                     | Yes                                        | Digits only, in the format used by your deployment. Must be unique across users.                   |
| **Designation**                      | Facility-based deployments, for some roles | Choose from the designations available for the role you selected.                                  |
| **Timezone**, **Culture** (language) | Where shown                                | Preferences of the user.                                                                           |

### Assignments

| Field                                              | When it appears                                                                   | Notes                                                                                                                                                   |
| -------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Assigned Health Facility**                       | Facility staff, community health workers, supervisors and facility administrators | The facility the user belongs to. The wording follows your deployment. Facility administrators can be assigned the district, sub-district and facility. |
| **Assigned Villages**                              | Community health workers and similar village-based roles                          | The villages the user serves. Only villages linked to the chosen facility are offered.                                                                  |
| **Community Unit**                                 | Community health assistants                                                       | Optional. Some other community roles show additional fields, such as a supervising organiser.                                                           |
| **Health Facility for Reports** / **for Insights** | Users with a **REPORTS** or **INSIGHTS** role                                     | The facilities whose data the user can see in those suites. Select all, or pick individual facilities.                                                  |
| **Red Risk**                                       | Facility-based deployments                                                        | A switch that marks the user as a red-risk user.                                                                                                        |

When you change the facility, the villages you selected are cleared, because villages depend on the facility. Choose the villages again.

### Validation errors

| Message                                                         | Cause                                                                                      |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Username already exists**, **Email ID already exists**        | Another user already has this username or email address.                                   |
| **Email ID already exists in different organization**           | The email address belongs to a user outside your area.                                     |
| **Username cannot contain spaces**                              | Remove the spaces.                                                                         |
| **Phone number already exists**                                 | Another user has this phone number.                                                        |
| **Multiple users can't have same ...**                          | Two rows in the same form use the same username, email or phone number.                    |
| **You dont have permission to add health facility admin**       | Your role cannot create facility administrators.                                           |
| **Username is not validated.** / **Email ID is not validated.** | The portal could not check uniqueness. Select **Validate username** or **Validate email**. |

## Find and filter users

On the **Users** page:

* Search by name, email or phone number.
* Select the filter icon to filter by facility, role and (for super administrators and managers across a region) district.
* The table shows **Name**, **Username**, **Role**, the facility, **Gender** (facility-based deployments) and **Contact Number**.

## Edit a user

1. Select the edit icon on the user's row.
2. Change the details. The username and email cannot be changed.
3. Select **Submit**.

A confirmation message, **User details updated successfully.**, appears. Facility administrators cannot edit other facility administrators.

## Activate or deactivate a user

Deactivating a user stops them from using SPICE but keeps their record. In community-based deployments, each row has an **Active** toggle. You cannot deactivate your own account.

1. Switch the **Active** toggle off on the user's row.
2. Confirm **Are you sure you want to deactivate this user?**
3. For a community health worker, the window also shows when the user last synced their data. A long gap means they may have unsynced work on their device, so check with them before you deactivate the account.

To activate a user again, switch the toggle on. For a community health worker you are asked to choose their villages again before saving, in a window titled **CHW Activate**. A user cannot be activated while their facility is deactivated: you see **Unable to activate user due to site deactivated.** Reactivate the facility first.

### Deactivating a community supervisor

A community supervisor who still has community health workers cannot simply be deactivated. The message says that users are assigned to the role and asks you to reassign them. Select **Reassign**, choose a new supervisor for each community health worker in the **CHW List**, and submit. Every worker needs a new supervisor, or you see **Please select peer supervisors for All CHWs**. If no other supervisor exists, select **Add Peer Supervisor** to create one first.

## Delete a user

1. Select the delete icon on the user's row.
2. Read the confirmation message and confirm.

For some community roles the message warns that the volunteers linked to the user will also be deleted. Delete removes the user from the portal. If you may need the account again, use the **Active** toggle instead.

Deleting an administrator from the **Admins** page removes them from all the sites linked to them, and the confirmation says so.

## Reset a password

### Reset a user's password as an administrator

An administrator can change the password only of an active user. Reactivate the user first if needed.

1. On the **Users** (or **Admins**) page, select the **Change Password** icon on the user's row.
2. In community-based deployments, under **Select Action**, choose how to reset the password:
   * **Change Password** to set a new password yourself.
   * **Reset by Email** to send the user a reset link.
3. If you chose **Change Password**, enter a **New Password** and **Confirm New Password**, then select **Submit**. Tell the user the new password through a secure channel.
4. If you chose **Reset by Email**, the window shows the email address that will receive the link. Select **Send Email**.

In other deployments the window goes straight to the new password fields.

### Reset your own password

Select your name at the top right, then **Change Password**. Enter your **Old Password**, then your **New Password** and **Confirm New Password**, and select **Submit**.

### When a user forgets their password

On the sign-in page, the user selects **Forgot password?**, enters their email address and submits. A link is emailed to them. The link opens a **Reset your password** page where they choose a new password and confirm it.

### Password rules

* 6 to 64 characters, with at least one uppercase letter, one lowercase letter and one number. Only letters and numbers are accepted.
* Not a common password, and not the same as the part of the email address before the @ sign.
* Confirm New Password must match.
* The new password cannot be the same as the old one (**New password cannot be same as old password.**).

### Limits and expiry

* Reset links expire after 60 minutes by default. An expired link shows **Link has expired.**
* A user can request only a limited number of reset emails in an hour (5 by default). After that you see **Password reset attempt exceeded. Please try after sometime.** Unlocking the user in [Account Lock & Unlock](https://spice.docs.medtroniclabs.org/admin-guide/account-lock-and-unlock.md) clears this counter.

## Consent forms and terms

* **Consent forms.** Each district can have its own consent text for the **Screening** and **Enrollment** forms. Super administrators and region administrators manage them from the district list or summary. See [Administrative Hierarchy](https://spice.docs.medtroniclabs.org/admin-guide/country-level-administrative-divisions.md).
* **Terms and conditions.** When your organisation has published terms and conditions, administrators (other than super administrators) must **Accept** them the first time they sign in.

## Your profile

Every user can open **My Profile** from the user menu. It shows **Name**, **Email ID**, **Mobile Number**, **Gender**, **Role**, **Timezone** and, for field roles, the **Supervisor** and **Villages**. Select **Edit My Profile** to update your details.

## Tips

* Create facilities before the users who belong to them.
* Give each user only the roles they need, and review administrator accounts regularly.
* Use the **Active** toggle rather than **Delete** when someone leaves temporarily.
* Check [Account Lock & Unlock](https://spice.docs.medtroniclabs.org/admin-guide/account-lock-and-unlock.md) first when a user says they cannot sign in.
