> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aquaops.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Users and Roles

> How user accounts and permission-key roles work today, and how to onboard staff.

This page explains how user accounts and roles work today.

## Best for

* onboarding staff
* assigning role-based access
* controlling who can view or edit different parts of the system

## Current access model

The current implementation uses roles with permission keys.

This is the implemented model today. A future roadmap item will move toward more granular permissions, but that is not active yet.

## Users

Go to:

```text theme={null}
Settings > Users
```

### Creating a user

Click `Add user` and provide:

* name
* email
* one or more roles

After creation, AquaOps generates a temporary password and shows it once.

<Warning>
  Copy the password immediately and share it securely with the user. The password will not be shown again after the dialog closes.
</Warning>

### User status

Users can be active or inactive. Inactive users should not be able to continue normal use of the app.

## Roles

Go to:

```text theme={null}
Settings > Roles
```

### Creating a role

Each role has:

* a name
* a list of permission keys

Permission keys are entered:

* one per line
* or comma-separated

### Example permission keys

* `chemical_records:view`
* `chemical_records:edit`
* `chemical_records:create`
* `chemical_records:view_own`
* `alerts:view`
* `forms:view`
* `forms:export`
* `form_submissions:create`
* `form_submissions:view`
* `*`

### The admin role

The built-in `admin` role name is protected and cannot be renamed because parts of the app rely on that role name during permission checks.

## Recommended role strategy

For a small deployment, start with:

* `admin`
* `manager`
* `operator`
* `readonly`

Then expand only if your organization actually needs more role separation.

## Typical walkthrough

<Steps>
  <Step title="Define roles">
    Open `Settings > Roles` and define the access patterns your team needs.
  </Step>

  <Step title="Open Users">
    Open `Settings > Users`.
  </Step>

  <Step title="Add staff">
    Add each staff member and assign the correct role set.
  </Step>

  <Step title="Deliver credentials">
    Copy the one-time temporary password and deliver it securely.
  </Step>

  <Step title="Manage access">
    Inactivate users when they should no longer have access.
  </Step>
</Steps>

## Suggested screenshots

* roles list
* role creation dialog
* users list
* add user dialog