Add role private attribute (#714)

Author: dorsha

README.md

@@ -975,16 +975,18 @@ descope_client.mgmt.role.create(
     name="My Role",
     description="Optional description to briefly explain what this role allows.",
     permission_names=["My Updated Permission"],
-    tenant_id="Optionally scope this role for this specific tenant. If left empty, the role will be available to all tenants."
+    tenant_id="Optionally scope this role for this specific tenant. If left empty, the role will be available to all tenants.",
+    private=False  # Optional, marks this role as private role
 )
 
 # Update will override all fields as is. Use carefully.
 descope_client.mgmt.role.update(
     name="My Role",
     new_name="My Updated Role",
     description="A revised description",
-    permission_names=["My Updated Permission", "Another Permission"]
-    tenant_id="The tenant ID to which this role is associated, leave empty, if role is a global one"
+    permission_names=["My Updated Permission", "Another Permission"],
+    tenant_id="The tenant ID to which this role is associated, leave empty, if role is a global one",
+    private=True  # Optional, marks this role as private role
 )
 
 # Role deletion cannot be undone. Use carefully.

descope/management/role.py

@@ -14,6 +14,7 @@ def create(
         permission_names: Optional[List[str]] = None,
         tenant_id: Optional[str] = None,
         default: Optional[bool] = None,
+        private: Optional[bool] = None,
     ):
         """
         Create a new role.
@@ -24,6 +25,7 @@ def create(
         permission_names (List[str]): Optional list of names of permissions this role grants.
         tenant_id (str): Optional tenant ID to create 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 creation operation fails
@@ -38,6 +40,7 @@ def create(
                 "permissionNames": permission_names,
                 "tenantId": tenant_id,
                 "default": default,
+                "private": private,
             },
         )
 
@@ -49,6 +52,7 @@ def update(
         permission_names: Optional[List[str]] = None,
         tenant_id: Optional[str] = None,
         default: Optional[bool] = None,
+        private: Optional[bool] = None,
     ):
         """
         Update an existing role with the given various fields. IMPORTANT: All parameters are used as overrides
@@ -61,6 +65,7 @@ def update(
         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
@@ -75,6 +80,7 @@ def update(
                 "permissionNames": permission_names,
                 "tenantId": tenant_id,
                 "default": default,
+                "private": private,
             },
         )
 

tests/management/test_role.py

@@ -45,7 +45,7 @@ def test_create(self):
         with patch("requests.post") as mock_post:
             mock_post.return_value.ok = True
             self.assertIsNone(
-                client.mgmt.role.create("R1", "Something", ["P1"], "t1", True)
+                client.mgmt.role.create("R1", "Something", ["P1"], "t1", True, False)
             )
             mock_post.assert_called_with(
                 f"{common.DEFAULT_BASE_URL}{MgmtV1.role_create_path}",
@@ -61,6 +61,7 @@ def test_create(self):
                     "permissionNames": ["P1"],
                     "tenantId": "t1",
                     "default": True,
+                    "private": False,
                 },
                 allow_redirects=False,
                 verify=True,
@@ -96,6 +97,7 @@ def test_update(self):
                     ["P1", "P2"],
                     "t1",
                     True,
+                    False,
                 )
             )
             mock_post.assert_called_with(
@@ -113,6 +115,7 @@ def test_update(self):
                     "permissionNames": ["P1", "P2"],
                     "tenantId": "t1",
                     "default": True,
+                    "private": False,
                 },
                 allow_redirects=False,
                 verify=True,
@@ -264,3 +267,117 @@ def test_search(self):
                 verify=True,
                 timeout=DEFAULT_TIMEOUT_SECONDS,
             )
+
+    def test_create_with_private_true(self):
+        client = DescopeClient(
+            self.dummy_project_id,
+            self.public_key_dict,
+            False,
+            self.dummy_management_key,
+        )
+
+        # Test private=True
+        with patch("requests.post") as mock_post:
+            mock_post.return_value.ok = True
+            self.assertIsNone(
+                client.mgmt.role.create(
+                    "PrivateRole", "Private role", ["P1"], "t1", False, True
+                )
+            )
+            mock_post.assert_called_with(
+                f"{common.DEFAULT_BASE_URL}{MgmtV1.role_create_path}",
+                headers={
+                    **common.default_headers,
+                    "Authorization": f"Bearer {self.dummy_project_id}:{self.dummy_management_key}",
+                    "x-descope-project-id": self.dummy_project_id,
+                },
+                params=None,
+                json={
+                    "name": "PrivateRole",
+                    "description": "Private role",
+                    "permissionNames": ["P1"],
+                    "tenantId": "t1",
+                    "default": False,
+                    "private": True,
+                },
+                allow_redirects=False,
+                verify=True,
+                timeout=DEFAULT_TIMEOUT_SECONDS,
+            )
+
+    def test_update_with_private_true(self):
+        client = DescopeClient(
+            self.dummy_project_id,
+            self.public_key_dict,
+            False,
+            self.dummy_management_key,
+        )
+
+        # Test private=True
+        with patch("requests.post") as mock_post:
+            mock_post.return_value.ok = True
+            self.assertIsNone(
+                client.mgmt.role.update(
+                    "role",
+                    "updated-role",
+                    "Updated private role",
+                    ["P1", "P2"],
+                    "t1",
+                    False,
+                    True,
+                )
+            )
+            mock_post.assert_called_with(
+                f"{common.DEFAULT_BASE_URL}{MgmtV1.role_update_path}",
+                headers={
+                    **common.default_headers,
+                    "Authorization": f"Bearer {self.dummy_project_id}:{self.dummy_management_key}",
+                    "x-descope-project-id": self.dummy_project_id,
+                },
+                params=None,
+                json={
+                    "name": "role",
+                    "newName": "updated-role",
+                    "description": "Updated private role",
+                    "permissionNames": ["P1", "P2"],
+                    "tenantId": "t1",
+                    "default": False,
+                    "private": True,
+                },
+                allow_redirects=False,
+                verify=True,
+                timeout=DEFAULT_TIMEOUT_SECONDS,
+            )
+
+    def test_create_without_private_parameter(self):
+        client = DescopeClient(
+            self.dummy_project_id,
+            self.public_key_dict,
+            False,
+            self.dummy_management_key,
+        )
+
+        # Test without private parameter (should be None)
+        with patch("requests.post") as mock_post:
+            mock_post.return_value.ok = True
+            self.assertIsNone(client.mgmt.role.create("SimpleRole", "Simple role"))
+            mock_post.assert_called_with(
+                f"{common.DEFAULT_BASE_URL}{MgmtV1.role_create_path}",
+                headers={
+                    **common.default_headers,
+                    "Authorization": f"Bearer {self.dummy_project_id}:{self.dummy_management_key}",
+                    "x-descope-project-id": self.dummy_project_id,
+                },
+                params=None,
+                json={
+                    "name": "SimpleRole",
+                    "description": "Simple role",
+                    "permissionNames": [],
+                    "tenantId": None,
+                    "default": None,
+                    "private": None,
+                },
+                allow_redirects=False,
+                verify=True,
+                timeout=DEFAULT_TIMEOUT_SECONDS,
+            )