> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles & Access Control

> How roles, user roles, and permissions control access to API endpoints across the Nexudus platform.

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

<Steps>
  <Step title="Roles (security/roles)">
    Granular, system-defined permissions tied to a specific entity and action.
  </Step>

  <Step title="UserRoles (security/userroles)">
    Named groups that bundle one or more Roles together, defined per location.
  </Step>

  <Step title="Users">
    Staff accounts assigned one or more UserRoles, which grants them all permissions contained in those groups.
  </Step>
</Steps>

***

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

| Suffix                | Permission granted             |
| --------------------- | ------------------------------ |
| `{EntityName}-List`   | Search and list records        |
| `{EntityName}-Read`   | Retrieve a single record by ID |
| `{EntityName}-Edit`   | Update existing records        |
| `{EntityName}-Create` | Create new records             |
| `{EntityName}-Delete` | Delete 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:

```bash theme={null}
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.

<Note>
  Roles cannot be created, modified, or deleted via the API. They are managed entirely by the platform.
</Note>

***

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

```bash theme={null}
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.

<Note>
  UserRoles are scoped to a location (`Business`), but the permissions they grant are **network-wide** — see the section on [cross-location access](#cross-location-access) below.
</Note>

***

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

<Tip>
  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.
</Tip>

***

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

```bash theme={null}
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.

***

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Search Roles" icon="shield" href="/rest-api/security/get-roles">
    Retrieve the full list of system-defined roles.
  </Card>

  <Card title="Search UserRoles" icon="users" href="/rest-api/security/get-userroles">
    List and manage UserRole permission groups.
  </Card>

  <Card title="Create UserRole" icon="plus" href="/rest-api/security/post-userroles">
    Create a new UserRole and assign roles to it.
  </Card>

  <Card title="Update UserRole" icon="pen" href="/rest-api/security/put-userroles">
    Modify an existing UserRole.
  </Card>
</CardGroup>