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

# Avalex Roles API — Staff Permissions and Access Control

> Manage staff roles and permission sets via the Avalex API. Each role defines a named collection of permission strings assigned to staff members.

The `/roles` resource lets you define and manage the permission sets that govern what staff members can do in Avalex. A role is a named bundle of permission strings — such as `customers:read` or `licenses:write` — that you assign to one or more staff accounts. By centralising permissions in roles, you can update access levels across your entire team by editing a single record.

## Required Permissions

| Action                | Permission     |
| --------------------- | -------------- |
| List / retrieve roles | `roles:read`   |
| Create / update roles | `roles:write`  |
| Delete roles          | `roles:delete` |

***

## List All Roles

<ParamField header="Authorization" type="string" required>
  Bearer `<token>` or Basic credentials.
</ParamField>

Returns an array of all role records in your Avalex account.

```bash theme={null}
curl http://localhost:8080/roles \
  -H "Authorization: Bearer <token>"
```

**Response — 200 OK**

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

***

## Create a Role

<ParamField header="Authorization" type="string" required>
  Bearer `<token>` or Basic credentials.
</ParamField>

<ParamField body="name" type="string" required>
  Human-readable name for the role (e.g. `Support Agent`).
</ParamField>

<ParamField body="permissions" type="string[]" required>
  Array of permission strings granted to this role. See the [full list of valid permissions](#valid-permission-strings) below.
</ParamField>

Creates a new role and returns the created record.

```bash theme={null}
curl -X POST http://localhost:8080/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "permissions": ["customers:read", "orders:read", "licenses:read"]
  }'
```

**Response — 201 Created**

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

***

## Get a Role by ID

<ParamField path="id" type="string" required>
  The unique role ID (e.g. `role_support`).
</ParamField>

Returns a single role record. Responds with `404 Not Found` if no role with that ID exists.

```bash theme={null}
curl http://localhost:8080/roles/role_support \
  -H "Authorization: Bearer <token>"
```

**Response — 200 OK**

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

***

## Update a Role

<ParamField path="id" type="string" required>
  The unique role ID.
</ParamField>

Performs a full replacement of the role record. The `permissions` array is replaced entirely with the value you provide. Returns `404 Not Found` if the role does not exist.

<Note>
  Changes to a role take effect immediately for all staff members assigned to it. Removing a permission from a role revokes that access across every staff account that holds the role.
</Note>

```bash theme={null}
curl -X PUT http://localhost:8080/roles/role_support \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "permissions": [
      "customers:read",
      "orders:read",
      "licenses:read",
      "products:read"
    ]
  }'
```

**Response — 200 OK**

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

***

## Delete a Role

<ParamField path="id" type="string" required>
  The unique role ID.
</ParamField>

Permanently removes the role record. Returns `204 No Content` on success and `404 Not Found` if the ID does not exist.

<Warning>
  Deleting a role removes it from every staff member it is assigned to. Ensure no active staff members depend on this role before deleting it.
</Warning>

```bash theme={null}
curl -X DELETE http://localhost:8080/roles/role_support \
  -H "Authorization: Bearer <token>"
```

**Response — 204 No Content**

***

## StaffRole Schema

<Expandable title="StaffRole fields">
  <ResponseField name="id" type="string">
    Unique identifier for the role (e.g. `role_support`). Assigned by Avalex on creation.
  </ResponseField>

  <ResponseField name="name" type="string">
    Human-readable display name of the role, shown in the dashboard and API responses.
  </ResponseField>

  <ResponseField name="permissions" type="string[]">
    Array of permission strings granted to staff members who hold this role. See the full list of valid values below.
  </ResponseField>
</Expandable>

### Full Schema Example

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

***

## Valid Permission Strings

The following permission strings are recognised by Avalex. Each string follows the `resource:action` pattern.

| Permission         | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `customers:read`   | View customer records                                  |
| `customers:write`  | Create and update customer records                     |
| `customers:delete` | Delete customer records                                |
| `products:read`    | View product catalog entries                           |
| `products:write`   | Create and update products                             |
| `products:delete`  | Delete products                                        |
| `licenses:read`    | View license records and validation history            |
| `licenses:write`   | Create and update licenses                             |
| `licenses:delete`  | Delete licenses                                        |
| `orders:read`      | View order records                                     |
| `orders:write`     | Create and update orders                               |
| `orders:delete`    | Delete orders                                          |
| `roles:read`       | View staff roles                                       |
| `roles:write`      | Create and update staff roles                          |
| `roles:delete`     | Delete staff roles                                     |
| `staff:read`       | View staff account details                             |
| `staff:manage`     | Update staff roles, toggle active status, delete staff |
| `actions:read`     | View audit log and action history                      |