> ## 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.

# Role-Based Access Control (RBAC) and Permissions in Avalex

> Understand how Avalex permission strings, staff roles, and the Master Admin account control access to every API resource and operation.

Avalex protects every authenticated API endpoint with a permission string checked at request time. When a staff member logs in and presents their JWT, the token carries the complete list of permissions assigned to their role. If the token does not include the permission required by the endpoint being called, Avalex returns a 403 response — regardless of who the caller is. This model makes it straightforward to give support staff read access without exposing destructive operations, and to scope integrations to only the resources they need.

## Permission String Format

Permission strings follow a `resource:action` pattern. The resource identifies the data model and the action identifies what can be done with it. For example:

* `customers:read` — fetch customer records
* `licenses:write` — create or update licenses
* `staff:manage` — create, update, and deactivate staff accounts

Every endpoint in the Avalex API documents which permission string it requires in its reference page.

## Full Permission Reference

| Permission         | Grants Access To                                         |
| ------------------ | -------------------------------------------------------- |
| `customers:read`   | List and retrieve customer records                       |
| `customers:write`  | Create and update customer records                       |
| `customers:delete` | Permanently delete customer records                      |
| `products:read`    | List and retrieve product definitions                    |
| `products:write`   | Create and update product definitions                    |
| `products:delete`  | Permanently delete product definitions                   |
| `licenses:read`    | List and retrieve license records and validation history |
| `licenses:write`   | Issue new licenses and update existing ones              |
| `licenses:delete`  | Revoke and permanently delete license records            |
| `orders:read`      | List and retrieve orders                                 |
| `orders:write`     | Create and update orders                                 |
| `orders:delete`    | Permanently delete orders                                |
| `roles:read`       | List and retrieve staff role definitions                 |
| `roles:write`      | Create and update staff role definitions                 |
| `roles:delete`     | Permanently delete staff role definitions                |
| `staff:read`       | List and retrieve staff account details                  |
| `staff:manage`     | Create, update, activate, and deactivate staff accounts  |
| `actions:read`     | Read the audit log and action history                    |

## The Master Admin Account

The Master Admin is a special built-in account that holds the wildcard permission `*`, granting unrestricted access to every endpoint and every resource. The Master Admin can also mint **registration keys** used to bootstrap new Avalex installations — an operation not available to any role-based account. Treat the Master Admin credentials with the same care as a root or superuser account: store the password in a secrets manager and avoid using it for day-to-day operations.

## Staff Roles

Rather than assigning permissions directly to individual staff members, you define **StaffRole** entities — named role templates that bundle a set of permission strings together. For example, a "Support Agent" role might include `customers:read`, `licenses:read`, and `orders:read`, while a "License Manager" role adds `licenses:write` and `orders:write` on top of that.

Once a role is defined, you assign it to one or more staff accounts. Changing the permissions on a role immediately affects every staff member assigned to it, without requiring individual account edits.

<Note>
  Staff accounts must have `active: true` to authenticate. If an account is deactivated, Avalex rejects login attempts and invalidates existing tokens for that account — even if the credentials are correct. Use deactivation to immediately revoke access when a team member leaves, without permanently deleting their audit trail.
</Note>

## Next Steps

<Card title="Managing Staff & Roles" icon="users-gear" href="/portal/staff">
  Learn how to create staff roles, assign permissions, onboard new team members, and deactivate accounts from the Admin Portal.
</Card>