feat(roles-permissions): add id-based management methods and role_ids search

descope/management/permission.py

@@ -54,7 +54,7 @@ def update_batch(
 
         Args:
         permissions (List[dict]): List of permission objects, each with:
-            - name (str): current permission name.
+            - name (str): current permission name (or id (str): permission ID, e.g. PERM...).
             - newName (str): new permission name.
             - description (str): Optional new description.
 
@@ -85,6 +85,25 @@ def delete_batch(
             body={"names": names},
         )
 
+    def delete_batch_by_ids(
+        self,
+        ids: List[str],
+    ):
+        """
+        Delete a batch of permissions by their IDs in a single atomic transaction.
+        IMPORTANT: This action is irreversible. Use carefully.
+
+        Args:
+        ids (List[str]): List of permission IDs to delete (e.g. PERM...).
+
+        Raise:
+        AuthException: raised if deletion operation fails
+        """
+        self._http.post(
+            MgmtV1.permission_delete_batch_path,
+            body={"ids": ids},
+        )
+
     def update(
         self,
         name: str,
@@ -108,6 +127,29 @@ def update(
             body={"name": name, "newName": new_name, "description": description},
         )
 
+    def update_by_id(
+        self,
+        id: str,
+        new_name: str,
+        description: Optional[str] = None,
+    ):
+        """
+        Update an existing permission identified by its ID. IMPORTANT: All parameters are used as overrides
+        to the existing permission. Empty fields will override populated fields. Use carefully.
+
+        Args:
+        id (str): permission ID (e.g. PERM...).
+        new_name (str): permission updated name.
+        description (str): Optional description to briefly explain what this permission allows.
+
+        Raise:
+        AuthException: raised if update operation fails
+        """
+        self._http.post(
+            MgmtV1.permission_update_path,
+            body={"id": id, "newName": new_name, "description": description},
+        )
+
     def delete(
         self,
         name: str,
@@ -126,6 +168,24 @@ def delete(
             body={"name": name},
         )
 
+    def delete_by_id(
+        self,
+        id: str,
+    ):
+        """
+        Delete an existing permission by its ID. IMPORTANT: This action is irreversible. Use carefully.
+
+        Args:
+        id (str): The ID of the permission to be deleted (e.g. PERM...).
+
+        Raise:
+        AuthException: raised if deletion operation fails
+        """
+        self._http.post(
+            MgmtV1.permission_delete_path,
+            body={"id": id},
+        )
+
     def load_all(
         self,
     ) -> dict:

descope/management/role.py

@@ -77,7 +77,7 @@ def update_batch(
 
         Args:
         roles (List[dict]): List of role objects, each with:
-            - name (str): current role name.
+            - name (str): current role name (or id (str): role ID, e.g. ROL...).
             - newName (str): new role name.
             - description (str): Optional new description.
             - permissionNames (List[str]): Optional list of permission names.
@@ -114,6 +114,27 @@ def delete_batch(
             body={"roles": roles},
         )
 
+    def delete_batch_by_ids(
+        self,
+        role_ids: List[str],
+        tenant_id: Optional[str] = None,
+    ):
+        """
+        Delete a batch of roles by their IDs in a single atomic transaction.
+        IMPORTANT: This action is irreversible. Use carefully.
+
+        Args:
+        role_ids (List[str]): List of role IDs to delete (e.g. ROL...).
+        tenant_id (str): Optional tenant ID the roles belong to.
+
+        Raise:
+        AuthException: raised if deletion operation fails
+        """
+        self._http.post(
+            MgmtV1.role_delete_batch_path,
+            body={"roleIds": role_ids, "tenantId": tenant_id},
+        )
+
     def update(
         self,
         name: str,
@@ -154,6 +175,46 @@ def update(
             },
         )
 
+    def update_by_id(
+        self,
+        id: str,
+        new_name: str,
+        description: Optional[str] = None,
+        permission_names: Optional[List[str]] = None,
+        tenant_id: Optional[str] = None,
+        default: Optional[bool] = None,
+        private: Optional[bool] = None,
+    ):
+        """
+        Update an existing role identified by its ID. IMPORTANT: All parameters are used as overrides
+        to the existing role. Empty fields will override populated fields. Use carefully.
+
+        Args:
+        id (str): role ID (e.g. ROL...).
+        new_name (str): role updated name.
+        description (str): Optional description to briefly explain what this role allows.
+        permission_names (List[str]): Optional list of names of permissions this role grants.
+        tenant_id (str): Optional tenant ID to update the role in.
+        default (bool): Optional marks this role as default role.
+        private (bool): Optional marks this role as private role.
+
+        Raise:
+        AuthException: raised if update operation fails
+        """
+        permission_names = [] if permission_names is None else permission_names
+        self._http.post(
+            MgmtV1.role_update_path,
+            body={
+                "id": id,
+                "newName": new_name,
+                "description": description,
+                "permissionNames": permission_names,
+                "tenantId": tenant_id,
+                "default": default,
+                "private": private,
+            },
+        )
+
     def delete(
         self,
         name: str,
@@ -173,6 +234,26 @@ def delete(
             body={"name": name, "tenantId": tenant_id},
         )
 
+    def delete_by_id(
+        self,
+        id: str,
+        tenant_id: Optional[str] = None,
+    ):
+        """
+        Delete an existing role by its ID. IMPORTANT: This action is irreversible. Use carefully.
+
+        Args:
+        id (str): The ID of the role to be deleted (e.g. ROL...).
+        tenant_id (str): Optional tenant ID the role belongs to.
+
+        Raise:
+        AuthException: raised if deletion operation fails
+        """
+        self._http.post(
+            MgmtV1.role_delete_path,
+            body={"id": id, "tenantId": tenant_id},
+        )
+
     def load_all(
         self,
     ) -> dict:
@@ -199,6 +280,7 @@ def search(
         role_name_like: Optional[str] = None,
         permission_names: Optional[List[str]] = None,
         include_project_roles: Optional[bool] = None,
+        role_ids: Optional[List[str]] = None,
     ) -> dict:
         """
         Search roles based on the given filters.
@@ -208,10 +290,11 @@ def search(
         role_names (List[str]): Only return matching roles to the given names
         role_name_like (str): Return roles that contain the given string ignoring case
         permission_names (List[str]): Only return roles that have the given permissions
+        role_ids (List[str]): Only return roles matching the given IDs (e.g. ROL...)
 
         Return value (dict):
         Return dict in the format
-             {"roles": [{"name": <name>, "description": <description>, "permissionNames":[]}] }
+             {"roles": [{"id": <id>, "name": <name>, "description": <description>, "permissionNames":[]}] }
         Containing the loaded role information.
 
         Raise:
@@ -228,6 +311,8 @@ def search(
             body["permissionNames"] = permission_names
         if include_project_roles is not None:
             body["includeProjectRoles"] = include_project_roles
+        if role_ids is not None:
+            body["roleIds"] = role_ids
 
         response = self._http.post(
             MgmtV1.role_search_path,