Zumri-Backend/Documentation/Permission-API.md

Permission API

Authentication

All endpoints require authentication token. Include in header:

Authorization: Bearer <token>

---

Permission Endpoints

Create Permission

Endpoint

POST: http://localhost:3070/api/permission

Authorization: Admin only

Request Body

{
  "permissionName": "Create Inquiry",
  "permissionDescription": "Permission to create new inquiries",
  "page": "inquiry",
  "module": "inquiry_management",
  "action": "create"
}

Response (201)

{
  "success": true,
  "data": {
    "permission_id": "inquiry_management.inquiry.create",
    "permissionName": "Create Inquiry",
    "permissionDescription": "Permission to create new inquiries",
    "page": "inquiry",
    "module": "inquiry_management",
    "action": "create",
    "createdAt": "2026-05-15T10:30:00Z",
    "updatedAt": "2026-05-15T10:30:00Z"
  }
}

---

Bulk Create Permissions

Endpoint

POST: http://localhost:3070/api/permission/bulk

Authorization: Admin only

Request Body

{
  "permissions": [
    {
      "permissionName": "Create Inquiry",
      "permissionDescription": "Permission to create new inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "create"
    },
    {
      "permissionName": "View Inquiry",
      "permissionDescription": "Permission to view inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "view"
    },
    {
      "permissionName": "Edit Inquiry",
      "permissionDescription": "Permission to edit inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "edit"
    }
  ]
}

Response (201)

{
  "success": true,
  "data": {
    "created": [
      {
        "permission_id": "inquiry_management.inquiry.create",
        "permissionName": "Create Inquiry",
        "permissionDescription": "Permission to create new inquiries",
        "page": "inquiry",
        "module": "inquiry_management",
        "action": "create"
      },
      {
        "permission_id": "inquiry_management.inquiry.view",
        "permissionName": "View Inquiry",
        "permissionDescription": "Permission to view inquiries",
        "page": "inquiry",
        "module": "inquiry_management",
        "action": "view"
      },
      {
        "permission_id": "inquiry_management.inquiry.edit",
        "permissionName": "Edit Inquiry",
        "permissionDescription": "Permission to edit inquiries",
        "page": "inquiry",
        "module": "inquiry_management",
        "action": "edit"
      }
    ],
    "failed": []
  }
}

---

Get All Permissions

Endpoint

GET: http://localhost:3070/api/permission

Response (200)

{
  "success": true,
  "data": [
    {
      "permission_id": "inquiry_management.inquiry.create",
      "permissionName": "Create Inquiry",
      "permissionDescription": "Permission to create new inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "create"
    },
    {
      "permission_id": "inquiry_management.inquiry.view",
      "permissionName": "View Inquiry",
      "permissionDescription": "Permission to view inquiries",
      "page": "inquiry",
      "module": "inquiry_management",
      "action": "view"
    }
  ]
}

---

Get Permission by ID

Endpoint

GET: http://localhost:3070/api/permission/:permissionId

Example

GET: http://localhost:3070/api/permission/inquiry_management.inquiry.create

Response (200)

{
  "success": true,
  "data": {
    "permission_id": "inquiry_management.inquiry.create",
    "permissionName": "Create Inquiry",
    "permissionDescription": "Permission to create new inquiries",
    "page": "inquiry",
    "module": "inquiry_management",
    "action": "create"
  }
}

---

Update Permission

Endpoint

PUT: http://localhost:3070/api/permission/:permissionId

Authorization: Admin only

Request Body

{
  "permissionName": "Create New Inquiry",
  "permissionDescription": "Updated permission to create new inquiries"
}

Response (200)

{
  "success": true,
  "data": {
    "permission_id": "inquiry_management.inquiry.create",
    "permissionName": "Create New Inquiry",
    "permissionDescription": "Updated permission to create new inquiries",
    "page": "inquiry",
    "module": "inquiry_management",
    "action": "create"
  },
  "message": "Permission updated successfully"
}

---

Delete Permission

Endpoint

DELETE: http://localhost:3070/api/permission/:permissionId

Authorization: Admin only

Response (200)

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

---

Role Endpoints

Create Role

Endpoint

POST: http://localhost:3070/api/permission/roles

Authorization: Admin only

Request Body

{
  "roleName": "Inquiry Manager",
  "roleDescription": "Role for managing inquiries"
}

Response (201)

{
  "success": true,
  "data": {
    "role_id": "role_1715843400000",
    "roleName": "Inquiry Manager",
    "roleDescription": "Role for managing inquiries",
    "createdAt": "2026-05-15T10:30:00Z",
    "updatedAt": "2026-05-15T10:30:00Z"
  }
}

---

Get All Roles

Endpoint

GET: http://localhost:3070/api/permission/roles

Response (200)

{
  "success": true,
  "data": [
    {
      "role_id": "role_1715843400000",
      "roleName": "Inquiry Manager",
      "roleDescription": "Role for managing inquiries",
      "rolePermissions": [
        {
          "rp_id": "rp_1715843500000",
          "role_id": "role_1715843400000",
          "permission_id": "inquiry_management.inquiry.create",
          "permission": {
            "permission_id": "inquiry_management.inquiry.create",
            "permissionName": "Create Inquiry",
            "page": "inquiry",
            "module": "inquiry_management",
            "action": "create"
          }
        }
      ]
    }
  ]
}

---

Get Role by ID

Endpoint

GET: http://localhost:3070/api/permission/roles/:roleId

Example

GET: http://localhost:3070/api/permission/roles/role_1715843400000

Response (200)

{
  "success": true,
  "data": {
    "role_id": "role_1715843400000",
    "roleName": "Inquiry Manager",
    "roleDescription": "Role for managing inquiries",
    "rolePermissions": [
      {
        "rp_id": "rp_1715843500000",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.create",
        "permission": {
          "permission_id": "inquiry_management.inquiry.create",
          "permissionName": "Create Inquiry",
          "page": "inquiry",
          "module": "inquiry_management",
          "action": "create"
        }
      }
    ]
  }
}

---

Update Role

Endpoint

PUT: http://localhost:3070/api/permission/roles/:roleId

Authorization: Admin only

Request Body

{
  "roleName": "Senior Inquiry Manager",
  "roleDescription": "Updated role for managing inquiries"
}

Response (200)

{
  "success": true,
  "data": {
    "role_id": "role_1715843400000",
    "roleName": "Senior Inquiry Manager",
    "roleDescription": "Updated role for managing inquiries"
  },
  "message": "Role updated successfully"
}

---

Delete Role

Endpoint

DELETE: http://localhost:3070/api/permission/roles/:roleId

Authorization: Admin only

Response (200)

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

---

Role-Permission Assignment Endpoints

Assign Permission to Role

Endpoint

POST: http://localhost:3070/api/permission/roles/:roleId/permissions

Authorization: Admin only

Request Body

{
  "role_id": "role_1715843400000",
  "permission_id": "inquiry_management.inquiry.create"
}

Response (201)

{
  "success": true,
  "data": {
    "rp_id": "rp_1715843500000",
    "role_id": "role_1715843400000",
    "permission_id": "inquiry_management.inquiry.create",
    "createdAt": "2026-05-15T10:30:00Z",
    "updatedAt": "2026-05-15T10:30:00Z"
  }
}

---

Bulk Assign Permissions to Role

Endpoint

POST: http://localhost:3070/api/permission/roles/permissions/bulk

Authorization: Admin only

Request Body

{
  "role_id": "role_1715843400000",
  "permission_ids": [
    "inquiry_management.inquiry.create",
    "inquiry_management.inquiry.view",
    "inquiry_management.inquiry.edit",
    "vendor_management.vendor.view"
  ]
}

Response (201)

{
  "success": true,
  "data": {
    "created": [
      {
        "rp_id": "rp_1715843500001",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.create"
      },
      {
        "rp_id": "rp_1715843500002",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.view"
      },
      {
        "rp_id": "rp_1715843500003",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.edit"
      },
      {
        "rp_id": "rp_1715843500004",
        "role_id": "role_1715843400000",
        "permission_id": "vendor_management.vendor.view"
      }
    ],
    "failed": []
  }
}

Response with Failures (201)

{
  "success": false,
  "data": {
    "created": [
      {
        "rp_id": "rp_1715843500001",
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.create"
      }
    ],
    "failed": [
      {
        "role_id": "role_1715843400000",
        "permission_id": "inquiry_management.inquiry.view",
        "error": "Role permission already exists"
      },
      {
        "role_id": "role_1715843400000",
        "permission_id": "nonexistent_permission",
        "error": "Permission not found"
      }
    ]
  }
}

---

User Permission Endpoints

Get User Permissions

Endpoint

GET: http://localhost:3070/api/permission/users/:userId/permissions

Example

GET: http://localhost:3070/api/permission/users/usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4/permissions

Response (200)

{
  "success": true,
  "data": [
    {
      "up_id": 1,
      "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
      "permission_id": "inquiry_management.inquiry.create",
      "permission": {
        "permission_id": "inquiry_management.inquiry.create",
        "permissionName": "Create Inquiry",
        "page": "inquiry",
        "module": "inquiry_management",
        "action": "create"
      }
    }
  ]
}

---

Create User Permission

Endpoint

POST: http://localhost:3070/api/permission/users/permissions

Authorization: Admin only

Request Body

{
  "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
  "permission_id": "inquiry_management.inquiry.create"
}

Response (201)

{
  "success": true,
  "data": {
    "up_id": 1,
    "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
    "permission_id": "inquiry_management.inquiry.create",
    "createdAt": "2026-05-15T10:30:00Z",
    "updatedAt": "2026-05-15T10:30:00Z"
  }
}

---

Bulk Create User Permissions

Endpoint

POST: http://localhost:3070/api/permission/users/permissions/bulk

Authorization: Admin only

Request Body

{
  "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
  "permission_ids": [
    "inquiry_management.inquiry.create",
    "inquiry_management.inquiry.view",
    "inquiry_management.inquiry.edit",
    "vendor_management.vendor.view"
  ]
}

Response (201)

{
  "success": true,
  "data": {
    "created": [
      {
        "up_id": 1,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.create"
      },
      {
        "up_id": 2,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.view"
      },
      {
        "up_id": 3,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.edit"
      },
      {
        "up_id": 4,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "vendor_management.vendor.view"
      }
    ],
    "failed": []
  }
}

Response with Failures (201)

{
  "success": false,
  "data": {
    "created": [
      {
        "up_id": 1,
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.create"
      }
    ],
    "failed": [
      {
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "inquiry_management.inquiry.view",
        "error": "User permission already exists"
      },
      {
        "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
        "permission_id": "nonexistent_permission",
        "error": "Permission not found"
      }
    ]
  }
}

---

Update User Permission

Endpoint

PUT: http://localhost:3070/api/permission/users/permissions/:upId

Authorization: Admin only

Request Body

{
  "permission_id": "inquiry_management.inquiry.edit"
}

Response (200)

{
  "success": true,
  "data": {
    "up_id": 1,
    "user_id": "usr_5ff8afec-5ddc-47d9-a63f-b43df0d8c3b4",
    "permission_id": "inquiry_management.inquiry.edit"
  },
  "message": "User permission updated successfully"
}

---

Delete User Permission

Endpoint

DELETE: http://localhost:3070/api/permission/users/permissions/:upId

Authorization: Admin only

Response (200)

{
  "success": true,
  "message": "User permission deleted successfully"
}

---

Error Responses

Bad Request (400)

{
  "success": false,
  "message": "Permission name, page, module, and action are required"
}

Not Found (404)

{
  "success": false,
  "message": "Permission not found"
}

Internal Server Error (500)

{
  "success": false,
  "message": "An error occurred while fetching permissions."
}