Avalex Roles API — Staff Permissions and Access Control

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

string

required

Bearer <token> or Basic credentials.

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

curl http://localhost:8080/roles \
  -H "Authorization: Bearer <token>"

Response — 200 OK

[
  {
    "id": "role_support",
    "name": "Support Agent",
    "permissions": ["customers:read", "orders:read", "licenses:read"]
  }
]

Create a Role

string

required

Bearer <token> or Basic credentials.

string

required

Human-readable name for the role (e.g. Support Agent).

string[]

required

Array of permission strings granted to this role. See the full list of valid permissions below.

Creates a new role and returns the created record.

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

{
  "id": "role_support",
  "name": "Support Agent",
  "permissions": ["customers:read", "orders:read", "licenses:read"]
}

Get a Role by ID

string

required

The unique role ID (e.g. role_support).

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

curl http://localhost:8080/roles/role_support \
  -H "Authorization: Bearer <token>"

Response — 200 OK

{
  "id": "role_support",
  "name": "Support Agent",
  "permissions": ["customers:read", "orders:read", "licenses:read"]
}

Update a Role

string

required

The unique role ID.

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.

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.

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

{
  "id": "role_support",
  "name": "Support Agent",
  "permissions": [
    "customers:read",
    "orders:read",
    "licenses:read",
    "products:read"
  ]
}

Delete a Role

string

required

The unique role ID.

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

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.

curl -X DELETE http://localhost:8080/roles/role_support \
  -H "Authorization: Bearer <token>"

Response — 204 No Content

StaffRole Schema

Show StaffRole fields

string

Unique identifier for the role (e.g. role_support). Assigned by Avalex on creation.

string

Human-readable display name of the role, shown in the dashboard and API responses.

string[]

Array of permission strings granted to staff members who hold this role. See the full list of valid values below.

Full Schema Example

{
  "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

Authentication

License Validation

Resources

Staff & Admin

Audit Logs

Avalex Roles API — Staff Permissions and Access Control

Required Permissions

List All Roles

Create a Role

Get a Role by ID

Update a Role

Delete a Role

StaffRole Schema

Full Schema Example

Valid Permission Strings

​Required Permissions

​List All Roles

​Create a Role

​Get a Role by ID

​Update a Role

​Delete a Role

​StaffRole Schema

​Full Schema Example

​Valid Permission Strings

Required Permissions

List All Roles

Create a Role

Get a Role by ID

Update a Role

Delete a Role

StaffRole Schema

Full Schema Example

Valid Permission Strings