Skip to main content

​
Roles & Access Control

The Nexudus REST API uses a role-based access control (RBAC) system to determine what each authenticated user can do. Understanding how roles are structured is essential for building integrations that create or manage admin users.

​
The Three Layers

Access control in Nexudus is made up of three parts that work together:
1

Roles (security/roles)

Granular, system-defined permissions tied to a specific entity and action.
2

UserRoles (security/userroles)

Named groups that bundle one or more Roles together, defined per location.
3

Users

Staff accounts assigned one or more UserRoles, which grants them all permissions contained in those groups.

​
Roles

Roles are read-only system records. They are created automatically by Nexudus whenever a new entity is added to the platform, and they follow a strict naming convention. Every entity in the system has exactly five roles associated with it:
SuffixPermission granted
{EntityName}-ListSearch and list records
{EntityName}-ReadRetrieve a single record by ID
{EntityName}-EditUpdate existing records
{EntityName}-CreateCreate new records
{EntityName}-DeleteDelete records
For example, the Booking entity has the following roles: Booking-List, Booking-Read, Booking-Edit, Booking-Create, and Booking-Delete. The full list of available roles can be retrieved at any time from the API: 
GET /api/security/roles
Because roles are auto-generated from entity names, the role catalogue always reflects the current state of the platform. When Nexudus adds a new entity, its five roles appear automatically.
Roles cannot be created, modified, or deleted via the API. They are managed entirely by the platform.

​
UserRoles

A UserRole is a named permission group that collects one or more Roles and can be assigned to users. You create and manage UserRoles yourself to match the access profiles needed in your organisation (e.g. Receptionist, Community Manager, Finance Admin). 
GET  /api/security/userroles
POST /api/security/userroles
PUT  /api/security/userroles
DELETE /api/security/userroles/{id}
A UserRole record has:
  • A name that describes the access profile.
  • A Business (location) it belongs to.
  • A collection of Roles that define what a user assigned to this group can do.
UserRoles are scoped to a location (Business), but the permissions they grant are network-wide — see the section on cross-location access below.

​
Assigning UserRoles to Users

Once a UserRole has been defined, it is assigned to a user (staff account). A user can hold multiple UserRoles, and their effective permissions are the union of all roles contained in every UserRole assigned to them. Permissions are the same regardless of which location the user is viewing. A staff member with Booking-Edit can edit bookings in every location they have been connected to (User.Businesses); there is no way to grant Booking-Edit only for a specific location.

​
Endpoint Authentication Requirements

Every endpoint documents its minimum role requirement in the Authentication section. For example:
The authenticated user must be a full unrestricted administrator or have the Booking-List role.
The pattern is consistent across the entire API:
HTTP methodRequired role pattern
GET (list / search){EntityName}-List
GET (single record){EntityName}-Read
POST{EntityName}-Create
PUT{EntityName}-Edit
DELETE{EntityName}-Delete
An authenticated user with no roles assigned (or only roles for unrelated entities) will receive a 401 Unauthorized response when calling these endpoints.
A full unrestricted administrator bypasses all role checks and has access to every endpoint. This is a special flag on the user account rather than a UserRole.

​
Cross-Location Access

Users are connected to one or more locations via User.Businesses. Their permissions apply uniformly across all connected locations — it is not possible to grant different roles per location.

​
The Customer (Coworker) Exception

Access to customer records (spaces/coworkers) has additional location-based scoping on top of the standard role checks:
  • A user with Coworker-List can search and view customers across every location in their network.
  • A user with Coworker-Edit can only modify a customer if their account is specifically connected to that customer’s Home Location (Coworker.InvoicingBusiness).
This means that an admin who manages multiple locations can see all customers regardless of where they belong, but write access to a customer is limited to admins whose account is linked to the location that owns that customer record. 
User connected to:  Location A, Location B
Customer home:      Location C

Result:
  Coworker-List  → can view the customer ✓
  Coworker-Edit  → cannot edit the customer ✗ (not connected to Location C)

​
Practical Example: Setting Up a Receptionist Role

The following steps show how to create a UserRole for a receptionist who can view and create bookings, and view (but not edit) customers. 1. Identify the required roles 
Booking-List
Booking-Read
Booking-Create
Coworker-List
Coworker-Read
2. Create the UserRole 
POST /api/security/userroles
Content-Type: application/json

{
  "Name": "Receptionist",
  "BusinessId": 12345,
  "Roles": [
    { "Id": "<Booking-List role id>" },
    { "Id": "<Booking-Read role id>" },
    { "Id": "<Booking-Create role id>" },
    { "Id": "<Coworker-List role id>" },
    { "Id": "<Coworker-Read role id>" }
  ]
}
3. Assign the UserRole to the user Update the user record to include the new UserRole in their assigned groups.

Search Roles

Retrieve the full list of system-defined roles.

Search UserRoles

List and manage UserRole permission groups.

Create UserRole

Create a new UserRole and assign roles to it.

Update UserRole

Modify an existing UserRole.