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

# Managing Staff and Roles in the Avalex Admin Portal

> Onboard staff members using single-use registration keys, assign permission-based roles, and deactivate accounts — all from the Avalex portal.

Avalex uses a two-part model for controlling what your team can do in the portal: **roles** define named bundles of permissions, and **staff accounts** are assigned one or more roles. This separation means you can create a role once — say, "Support Agent" — and apply it to as many staff members as needed, then update the permissions in one place if your requirements change. Staff members self-register using a single-use key generated by the Master Admin, so you never need to set passwords on behalf of your team.

## Part 1 — Creating a Role

Roles determine what a staff member can see and do across the portal. You should create your roles before onboarding any staff so you can assign them immediately upon registration.

<Steps>
  <Step title="Navigate to Roles">
    Go to **Staff & Roles** in the sidebar, then select the **Roles** tab.
  </Step>

  <Step title="Create a new role">
    Click **Create Role** and give it a descriptive name, such as `Support Agent` or `License Manager`.
  </Step>

  <Step title="Add permissions">
    Select the permission strings that this role should grant. Refer to the table below for a full list of available permissions.
  </Step>

  <Step title="Save the role">
    Click **Save**. The role is now available to assign to staff members.
  </Step>
</Steps>

### Available Permissions

| Permission         | What It Grants                                  |
| ------------------ | ----------------------------------------------- |
| `customers:read`   | View customer records                           |
| `customers:write`  | Create and update customers                     |
| `customers:delete` | Delete customer records                         |
| `products:read`    | View product definitions                        |
| `products:write`   | Create and update products                      |
| `products:delete`  | Delete products                                 |
| `licenses:read`    | View license records                            |
| `licenses:write`   | Issue and modify licenses                       |
| `licenses:delete`  | Delete licenses                                 |
| `orders:read`      | View orders                                     |
| `orders:write`     | Create and update orders                        |
| `orders:delete`    | Delete orders                                   |
| `roles:read`       | View roles and their permissions                |
| `roles:write`      | Create and update roles                         |
| `roles:delete`     | Delete roles                                    |
| `staff:read`       | View staff accounts                             |
| `staff:manage`     | Deactivate, reactivate, and edit staff accounts |
| `actions:read`     | View the audit log                              |

### Role Schema

```json theme={null}
{
  "id": "role_support",
  "name": "Support Agent",
  "permissions": ["customers:read", "orders:read", "licenses:read"]
}
```

## Part 2 — Onboarding a Staff Member

New staff members register themselves using a single-use registration key that you generate from the portal. This flow ensures that only people you explicitly invite can create accounts.

<Steps>
  <Step title="Generate a registration key">
    As the Master Admin, navigate to **Admin > Registration Keys** and click **Generate Key**.
  </Step>

  <Step title="Copy and send the key">
    Copy the key immediately — it is displayed only once and cannot be retrieved afterward. Send it to the new staff member through a secure channel.
  </Step>

  <Step title="Staff member registers">
    The new staff member calls `POST /staff/register` with the key, their chosen username, email address, and a password (minimum 8 characters). Their account is created automatically once the key is validated.
  </Step>

  <Step title="Assign roles">
    In the portal, go to **Staff**, find the new account, click **Edit Roles**, and assign the appropriate role or roles.
  </Step>
</Steps>

<Note>
  Registration keys are single-use. Once a key has been consumed during registration it cannot be reused. If a key is lost or expires before use, generate a new one from the Registration Keys page.
</Note>

<Warning>
  Only the Master Admin can generate registration keys. Staff members with the `staff:manage` permission can edit accounts and assign roles, but they cannot create new registration keys.
</Warning>

## Part 3 — Deactivating or Deleting Staff

When a staff member leaves your organization or no longer needs portal access, you have two options:

* **Deactivate** — Set the account's `active` flag to `false`. This immediately prevents the staff member from logging in without permanently removing their account or its audit history. You can reactivate the account at any time.
* **Delete** — Permanently removes the staff account. Use this option only when you are certain the account and its history are no longer needed.

In most cases, deactivating is the safer choice because it preserves the audit trail associated with that staff member's past actions.