Roles & Permissions API

Manage RBAC roles — create, list, update, delete, and seed defaults. Each role defines granular permissions across 19 modules with 5 permission levels each.

Endpoints

Method	Path	Description
GET	`/api/roles/permissions-meta`	Get all available permission modules and actions
GET	`/api/roles/:orgId/list`	List all roles
POST	`/api/roles/:orgId/create`	Create a new role
POST	`/api/roles/:orgId/seed`	Seed default roles
GET	`/api/roles/:orgId/:roleId`	Get role by ID
PUT	`/api/roles/:orgId/:roleId/update`	Update a role
DELETE	`/api/roles/:orgId/:roleId/delete`	Delete a role

Path Parameters

Parameter	Type	Description
`orgId`	`string`	Organization ID
`roleId`	`string`	Role ID

RBAC Modules

The system enforces permissions across 19 modules:

#	Module	Description
1	`bookings`	Room bookings
2	`invoices`	Invoice management
3	`payments`	Payment records
4	`expenses`	Expense tracking
5	`quotes`	Quotation management
6	`credit_notes`	Credit notes
7	`guests`	Guest profiles
8	`rooms`	Room inventory
9	`room_categories`	Room category configuration
10	`users`	User management
11	`organization`	Organization settings
12	`roles`	Role & permission management
13	`taxes`	Tax configuration
14	`accounts`	Chart of accounts
15	`vendors`	Vendor management
16	`series`	Auto-numbering series
17	`notifications`	Notification settings
18	`email_templates`	Email template management
19	`audit_logs`	Audit log viewing

Each module supports 5 permission levels: view, create, update, delete, manage.

Get Permissions Meta

GET /api/roles/permissions-meta

Response — `200 OK`

json

{
  "success": true,
  "data": {
    "modules": [
      "bookings", "invoices", "payments", "expenses", "quotes",
      "credit_notes", "guests", "rooms", "room_categories", "users",
      "organization", "roles", "taxes", "accounts", "vendors",
      "series", "notifications", "email_templates", "audit_logs"
    ],
    "actions": ["view", "create", "update", "delete", "manage"]
  }
}

List Roles

GET /api/roles/:orgId/list

Response — `200 OK`

json

{
  "success": true,
  "data": [
    {
      "_id": "665b2c3d4e5f6a7b8c9d0e1f",
      "name": "Admin",
      "description": "Full access to all modules",
      "isDefault": true,
      "usersCount": 2,
      "createdAt": "2026-02-20T08:00:00.000Z"
    },
    {
      "_id": "665b2c3d4e5f6a7b8c9d0e20",
      "name": "Front Desk",
      "description": "Booking and guest management",
      "isDefault": true,
      "usersCount": 4,
      "createdAt": "2026-02-20T08:00:00.000Z"
    },
    {
      "_id": "665b2c3d4e5f6a7b8c9d0e21",
      "name": "Accountant",
      "description": "Financial operations only",
      "isDefault": false,
      "usersCount": 1,
      "createdAt": "2026-02-21T14:00:00.000Z"
    }
  ]
}

Create Role

POST /api/roles/:orgId/create

Request Body

json

{
  "name": "Accountant",
  "description": "Financial operations only",
  "permissions": {
    "bookings":        { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "invoices":        { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
    "payments":        { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
    "expenses":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": false },
    "quotes":          { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
    "credit_notes":    { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
    "guests":          { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "rooms":           { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "room_categories": { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "users":           { "view": false, "create": false, "update": false, "delete": false, "manage": false },
    "organization":    { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "roles":           { "view": false, "create": false, "update": false, "delete": false, "manage": false },
    "taxes":           { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "accounts":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "vendors":         { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": false },
    "series":          { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "notifications":   { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "email_templates": { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "audit_logs":      { "view": true,  "create": false, "update": false, "delete": false, "manage": false }
  }
}

Response — `201 Created`

json

{
  "success": true,
  "message": "Role created successfully",
  "data": {
    "_id": "665b2c3d4e5f6a7b8c9d0e21",
    "name": "Accountant",
    "description": "Financial operations only",
    "permissions": {
      "bookings":        { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "invoices":        { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
      "payments":        { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
      "expenses":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": false },
      "quotes":          { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
      "credit_notes":    { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
      "guests":          { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "rooms":           { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "room_categories": { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "users":           { "view": false, "create": false, "update": false, "delete": false, "manage": false },
      "organization":    { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "roles":           { "view": false, "create": false, "update": false, "delete": false, "manage": false },
      "taxes":           { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
      "accounts":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
      "vendors":         { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": false },
      "series":          { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "notifications":   { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "email_templates": { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "audit_logs":      { "view": true,  "create": false, "update": false, "delete": false, "manage": false }
    },
    "orgId": "663f1a2b3c4d5e6f7a8b9c0d",
    "isDefault": false,
    "createdAt": "2026-02-23T11:00:00.000Z",
    "updatedAt": "2026-02-23T11:00:00.000Z"
  }
}

Seed Default Roles

POST /api/roles/:orgId/seed

Seeds the organization with default roles (e.g. Admin, Front Desk, Housekeeping).

Response — `201 Created`

json

{
  "success": true,
  "message": "Default roles seeded successfully",
  "data": {
    "rolesCreated": 3,
    "roles": ["Admin", "Front Desk", "Housekeeping"]
  }
}

Get Role by ID

GET /api/roles/:orgId/:roleId

Response — `200 OK`

json

{
  "success": true,
  "data": {
    "_id": "665b2c3d4e5f6a7b8c9d0e21",
    "name": "Accountant",
    "description": "Financial operations only",
    "permissions": {
      "bookings":        { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "invoices":        { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
      "payments":        { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
      "expenses":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": false },
      "quotes":          { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
      "credit_notes":    { "view": true,  "create": true,  "update": true,  "delete": false, "manage": false },
      "guests":          { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "rooms":           { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "room_categories": { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "users":           { "view": false, "create": false, "update": false, "delete": false, "manage": false },
      "organization":    { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "roles":           { "view": false, "create": false, "update": false, "delete": false, "manage": false },
      "taxes":           { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
      "accounts":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
      "vendors":         { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": false },
      "series":          { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "notifications":   { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "email_templates": { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
      "audit_logs":      { "view": true,  "create": false, "update": false, "delete": false, "manage": false }
    },
    "orgId": "663f1a2b3c4d5e6f7a8b9c0d",
    "isDefault": false,
    "createdAt": "2026-02-23T11:00:00.000Z",
    "updatedAt": "2026-02-23T11:00:00.000Z"
  }
}

Update Role

PUT /api/roles/:orgId/:roleId/update

Request Body

json

{
  "name": "Senior Accountant",
  "description": "Full financial access with vendor management",
  "permissions": {
    "bookings":        { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "invoices":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "payments":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "expenses":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "quotes":          { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": false },
    "credit_notes":    { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "guests":          { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "rooms":           { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "room_categories": { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "users":           { "view": false, "create": false, "update": false, "delete": false, "manage": false },
    "organization":    { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "roles":           { "view": false, "create": false, "update": false, "delete": false, "manage": false },
    "taxes":           { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "accounts":        { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "vendors":         { "view": true,  "create": true,  "update": true,  "delete": true,  "manage": true  },
    "series":          { "view": true,  "create": false, "update": true,  "delete": false, "manage": false },
    "notifications":   { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "email_templates": { "view": true,  "create": false, "update": false, "delete": false, "manage": false },
    "audit_logs":      { "view": true,  "create": false, "update": false, "delete": false, "manage": false }
  }
}

Response — `200 OK`

json

{
  "success": true,
  "message": "Role updated successfully",
  "data": {
    "_id": "665b2c3d4e5f6a7b8c9d0e21",
    "name": "Senior Accountant",
    "description": "Full financial access with vendor management",
    "orgId": "663f1a2b3c4d5e6f7a8b9c0d",
    "isDefault": false,
    "createdAt": "2026-02-23T11:00:00.000Z",
    "updatedAt": "2026-02-23T14:00:00.000Z"
  }
}

Delete Role

DELETE /api/roles/:orgId/:roleId/delete

Response — `200 OK`

json

{
  "success": true,
  "message": "Role deleted successfully"
}

Roles & Permissions API ​

Endpoints ​

Path Parameters ​

RBAC Modules ​

Get Permissions Meta ​

Response — 200 OK ​

List Roles ​

Response — 200 OK ​

Create Role ​

Request Body ​

Response — 201 Created ​

Seed Default Roles ​

Response — 201 Created ​

Get Role by ID ​

Response — 200 OK ​

Update Role ​

Request Body ​

Response — 200 OK ​

Delete Role ​

Response — 200 OK ​

Roles & Permissions API

Endpoints

Path Parameters

RBAC Modules

Get Permissions Meta

Response — `200 OK`

List Roles

Response — `200 OK`

Create Role

Request Body

Response — `201 Created`

Seed Default Roles

Response — `201 Created`

Get Role by ID

Response — `200 OK`

Update Role

Request Body

Response — `200 OK`

Delete Role

Response — `200 OK`