Avalex Staff API — Manage Accounts and Permissions

The /staff endpoints let you manage the human operators who access your Avalex dashboard and API. You can list all staff accounts, look up an individual member, reassign roles, deactivate or reactivate accounts, and permanently remove a staff member. All management actions require the staff:manage permission, while read-only lookups require staff:read.

Creating a new staff account requires a valid, unused registration key. Registration keys are generated by the Master Admin and consumed on first use. See the Registration Keys page for details.

Required Permissions

Action	Permission
List / retrieve staff	`staff:read`
Update roles, active status, or delete	`staff:manage`
Register a new staff account	None — requires a valid registration key

List All Staff

string

required

Bearer <token> or Basic credentials.

Returns an array of all staff accounts as StaffPublicView objects.

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

Response — 200 OK

[
  {
    "id": "e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef",
    "username": "newstaff",
    "email": "staff@example.com",
    "roleIds": ["role_support"],
    "active": true
  }
]

Get a Staff Member by ID

string

required

The UUID of the staff member (e.g. e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef).

Returns a single StaffPublicView. Responds with 404 Not Found if no staff member with that ID exists.

curl http://localhost:8080/staff/e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef \
  -H "Authorization: Bearer <token>"

Response — 200 OK

{
  "id": "e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef",
  "username": "newstaff",
  "email": "staff@example.com",
  "roleIds": ["role_support"],
  "active": true
}

Update Staff Roles

string

required

The UUID of the staff member.

string[]

required

Complete list of role IDs to assign to this staff member. Replaces the current set entirely.

Replaces the staff member’s role assignments with the provided array. Returns 404 Not Found if the staff member does not exist.

This endpoint replaces all existing role assignments. To add a role without removing others, retrieve the current roleIds first, append the new ID, then submit the full updated array.

curl -X PUT http://localhost:8080/staff/e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "roleIds": ["role_support", "role_billing"]
  }'

Response — 200 OK

{
  "id": "e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef",
  "username": "newstaff",
  "email": "staff@example.com",
  "roleIds": ["role_support", "role_billing"],
  "active": true
}

Update Staff Active Status

string

required

The UUID of the staff member.

boolean

required

Set to false to deactivate the account, or true to reactivate it.

Toggles the active status of a staff account. Deactivated accounts cannot authenticate or use the API. Returns 404 Not Found if the staff member does not exist.

curl -X PUT http://localhost:8080/staff/e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef/active \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

Response — 200 OK

{
  "id": "e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef",
  "username": "newstaff",
  "email": "staff@example.com",
  "roleIds": ["role_support"],
  "active": false
}

Delete a Staff Member

string

required

The UUID of the staff member to delete.

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

This action is irreversible. The deleted staff member will need to register a new account using a fresh registration key if access is required again.

curl -X DELETE http://localhost:8080/staff/e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef \
  -H "Authorization: Bearer <token>"

Response — 204 No Content

Register a New Staff Member

This endpoint is public and does not require an authenticated session, but it does require a valid, unused registration key issued by the Master Admin.

string

required

A single-use registration key generated via POST /admin/registration-keys.

string

required

Desired username for the new staff account.

string

required

Email address for the new staff account.

string

required

Password for the new account. Must be at least 8 characters long.

string[]

required

Array of role IDs to assign to the new staff member on registration.

Creates a new staff account and returns a StaffPublicView. The registration key is consumed and cannot be reused.

curl -X POST http://localhost:8080/staff/register \
  -H "Content-Type: application/json" \
  -d '{
    "registrationKey": "a1b2c3d4e5f67890abcdef1234567890",
    "username": "newstaff",
    "email": "staff@example.com",
    "password": "securepassword123",
    "roleIds": ["role_support"]
  }'

Response — 201 Created

{
  "id": "e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef",
  "username": "newstaff",
  "email": "staff@example.com",
  "roleIds": ["role_support"],
  "active": true
}

Error Responses

400 Bad Request — Password too short:

{
  "error": "Password must be at least 8 characters"
}

403 Forbidden — Key not recognised:

{
  "error": "Invalid registration key"
}

403 Forbidden — Key already consumed:

{
  "error": "This registration key has already been used"
}

StaffPublicView Schema

Show StaffPublicView fields

string

UUID assigned to the staff member on registration (e.g. e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef).

string

Unique username chosen at registration.

string

Email address associated with the staff account.

string[]

Array of role IDs currently assigned to this staff member. Roles determine which permissions the account holds.

boolean

Whether the account is currently active. Inactive accounts cannot authenticate.

Full Schema Example

{
  "id": "e9f0d1c2-b3a4-5678-cdef-90ab12cd34ef",
  "username": "newstaff",
  "email": "staff@example.com",
  "roleIds": ["role_support"],
  "active": true
}

Authentication

License Validation

Resources

Staff & Admin

Audit Logs

Avalex Staff API — Manage Accounts and Permissions

Required Permissions

List All Staff

Get a Staff Member by ID

Update Staff Roles

Update Staff Active Status

Delete a Staff Member

Register a New Staff Member

Error Responses

StaffPublicView Schema

Full Schema Example

​Required Permissions

​List All Staff

​Get a Staff Member by ID

​Update Staff Roles

​Update Staff Active Status

​Delete a Staff Member

​Register a New Staff Member

​Error Responses

​StaffPublicView Schema

​Full Schema Example

Required Permissions

List All Staff

Get a Staff Member by ID

Update Staff Roles

Update Staff Active Status

Delete a Staff Member

Register a New Staff Member

Error Responses

StaffPublicView Schema

Full Schema Example