Merge branch 'main' into separate-clients

# Conflicts:
#	descope/auth.py
#	descope/descope_client.py
#	descope/management/fga.py
#	descope/management/user.py

Author: itaihanski

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
       - id: flake8
         additional_dependencies: [Flake8-pyproject]
   - repo: https://github.com/python-poetry/poetry
-    rev: 2.1.4
+    rev: 2.2.0
     hooks:
       - id: poetry-export
         files: pyproject.toml

README.md

@@ -1224,6 +1224,26 @@ relations = descope_client.mgmt.fga.check(
 )
 ```
 
+Response times of repeated FGA `check` calls, especially in high volume scenarios, can be reduced to sub-millisecond scales by re-directing the calls to a Descope FGA Cache Proxy running in the same backend cluster as your application.
+After setting up the proxy server via the Descope provided Docker image, set the `fga_cache_url` parameter to be equal to the proxy URL to enable its use in the SDK, as shown in the example below:
+
+```python
+# Initialize client with FGA cache URL
+descope_client = DescopeClient(
+    project_id="<Project ID>",
+    management_key="<Management Key>",
+    fga_cache_url="https://10.0.0.4",  # example FGA Cache Proxy URL, running inside the same backend cluster
+)
+```
+
+When the `fga_cache_url` is configured, the following FGA methods will automatically use the cache proxy instead of the default Descope API:
+- `save_schema`
+- `create_relations`  
+- `delete_relations`
+- `check`
+
+Other FGA operations like `load_schema` will continue to use the standard Descope API endpoints.
+
 ### Manage Project
 
 You can change the project name, as well as clone the current project to

descope/auth.py

@@ -9,6 +9,7 @@
 from typing import Iterable, Optional
 
 import jwt
+import requests
 from email_validator import EmailNotValidError, validate_email
 from jwt import ExpiredSignatureError, ImmatureSignatureError
 
@@ -66,7 +67,6 @@ def __init__(
         self.project_id = project_id
         self.jwt_validation_leeway = jwt_validation_leeway
 
-        # Internal HTTP client for all network traffic (must be injected)
         self._http = http_client
 
         public_key = public_key or os.getenv("DESCOPE_PUBLIC_KEY")
@@ -447,13 +447,13 @@ def _validate_token(
                 audience=audience,
                 leeway=self.jwt_validation_leeway,
             )
-        except (ImmatureSignatureError):
+        except ImmatureSignatureError:
             raise AuthException(
                 400,
                 ERROR_TYPE_INVALID_TOKEN,
                 "Received Invalid token (nbf in future) during jwt validation. Error can be due to time glitch (between machines), try to set the jwt_validation_leeway parameter (in DescopeClient) to higher value than 5sec which is the default",
             )
-        except (ExpiredSignatureError):
+        except ExpiredSignatureError:
             raise AuthException(
                 401,
                 ERROR_TYPE_INVALID_TOKEN,

descope/descope_client.py

@@ -30,9 +30,10 @@ def __init__(
         public_key: Optional[dict] = None,
         skip_verify: bool = False,
         management_key: Optional[str] = None,
-        auth_management_key: Optional[str] = None,
         timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS,
         jwt_validation_leeway: int = 5,
+        auth_management_key: Optional[str] = None,
+        fga_cache_url: str | None = None,
     ):
         # Auth Initialization
         auth_http_client = HTTPClient(
@@ -68,6 +69,7 @@ def __init__(
         )
         self._mgmt = MGMT(
             http_client=mgmt_http_client,
+            fga_cache_url=fga_cache_url,
         )
 
     @property

descope/http_client.py

@@ -95,9 +95,10 @@ def post(
         body: Optional[Union[dict, list[dict], list[str]]] = None,
         params=None,
         pswd: Optional[str] = None,
+        base_url: Optional[str] = None,
     ) -> requests.Response:
         response = requests.post(
-            f"{self.base_url}{uri}",
+            f"{base_url or self.base_url}{uri}",
             headers=self._get_default_headers(pswd),
             json=body,
             allow_redirects=False,

descope/management/common.py

@@ -68,6 +68,7 @@ class MgmtV1:
     user_create_batch_path = "/v1/mgmt/user/create/batch"
     user_update_path = "/v1/mgmt/user/update"
     user_patch_path = "/v1/mgmt/user/patch"
+    user_patch_batch_path = "/v1/mgmt/user/patch/batch"
     user_delete_path = "/v1/mgmt/user/delete"
     user_logout_path = "/v1/mgmt/user/logout"
     user_delete_all_test_users_path = "/v1/mgmt/user/test/delete/all"

descope/management/fga.py

@@ -5,6 +5,11 @@
 
 
 class FGA(HTTPBase):
+
+    def __init__(self, http_client, fga_cache_url: str | None = None):
+        super().__init__(http_client)
+        self._fga_cache_url = fga_cache_url
+
     def save_schema(self, schema: str):
         """
         Create or update an FGA schema.
@@ -43,6 +48,7 @@ def save_schema(self, schema: str):
         self._http.post(
             MgmtV1.fga_save_schema,
             body={"dsl": schema},
+            base_url=self._fga_cache_url,
         )
 
     def create_relations(
@@ -66,6 +72,7 @@ def create_relations(
         self._http.post(
             MgmtV1.fga_create_relations,
             body={"tuples": relations},
+            base_url=self._fga_cache_url,
         )
 
     def delete_relations(
@@ -82,6 +89,7 @@ def delete_relations(
         self._http.post(
             MgmtV1.fga_delete_relations,
             body={"tuples": relations},
+            base_url=self._fga_cache_url,
         )
 
     def check(
@@ -120,6 +128,7 @@ def check(
         response = self._http.post(
             MgmtV1.fga_check,
             body={"tuples": relations},
+            base_url=self._fga_cache_url,
         )
         return list(
             map(

descope/management/user.py

@@ -417,6 +417,7 @@ def patch(
         verified_email: Optional[bool] = None,
         verified_phone: Optional[bool] = None,
         sso_app_ids: Optional[List[str]] = None,
+        status: Optional[str] = None,
         test: bool = False,
     ) -> dict:
         """
@@ -437,6 +438,7 @@ def patch(
         picture (str): Optional url for user picture
         custom_attributes (dict): Optional, set the different custom attributes values of the keys that were previously configured in Descope console app
         sso_app_ids (List[str]): Optional, list of SSO applications IDs to be associated with the user.
+        status (str): Optional status field. Can be one of: "enabled", "disabled", "invited".
         test (bool, optional): Set to True to update a test user. Defaults to False.
 
         Return value (dict):
@@ -447,6 +449,12 @@ def patch(
         Raise:
         AuthException: raised if patch operation fails
         """
+        if status is not None and status not in ["enabled", "disabled", "invited"]:
+            raise AuthException(
+                400,
+                ERROR_TYPE_INVALID_ARGUMENT,
+                f"Invalid status value: {status}. Must be one of: enabled, disabled, invited",
+            )
         response = self._http.patch(
             MgmtV1.user_patch_path,
             body=User._compose_patch_body(
@@ -464,11 +472,53 @@ def patch(
                 verified_email,
                 verified_phone,
                 sso_app_ids,
+                status,
                 test,
             ),
         )
         return response.json()
 
+    def patch_batch(
+        self,
+        users: List[UserObj],
+        test: bool = False,
+    ) -> dict:
+        """
+        Patch users in batch. Only the provided fields will be updated for each user.
+
+        Args:
+        users (List[UserObj]): A list of UserObj instances representing users to be patched.
+            Each UserObj should have a login_id and the fields to be updated.
+        test (bool, optional): Set to True to patch test users. Defaults to False.
+
+        Return value (dict):
+        Return dict in the format
+             {"patchedUsers": [...], "failedUsers": [...]}
+        "patchedUsers" contains successfully patched users,
+        "failedUsers" contains users that failed to be patched with error details.
+
+        Raise:
+        AuthException: raised if patch batch operation fails
+        """
+        # Validate status fields for all users
+        for user in users:
+            if user.status is not None and user.status not in [
+                "enabled",
+                "disabled",
+                "invited",
+            ]:
+                raise AuthException(
+                    400,
+                    ERROR_TYPE_INVALID_ARGUMENT,
+                    f"Invalid status value: {user.status} for user {user.login_id}. Must be one of: enabled, disabled, invited",
+                )
+
+        response = self._http.patch(
+            MgmtV1.user_patch_batch_path,
+            body=User._compose_patch_batch_body(users, test),
+        )
+        return response.json()
+
     def delete(
         self,
         login_id: str,
@@ -1924,6 +1974,7 @@ def _compose_patch_body(
         verified_email: Optional[bool],
         verified_phone: Optional[bool],
         sso_app_ids: Optional[List[str]],
+        status: Optional[str],
         test: bool = False,
     ) -> dict:
         res: dict[str, Any] = {
@@ -1955,6 +2006,37 @@ def _compose_patch_body(
             res["verifiedPhone"] = verified_phone
         if sso_app_ids is not None:
             res["ssoAppIds"] = sso_app_ids
+        if status is not None:
+            res["status"] = status
         if test:
             res["test"] = test
         return res
+
+    @staticmethod
+    def _compose_patch_batch_body(
+        users: List[UserObj],
+        test: bool = False,
+    ) -> dict:
+        users_body = []
+        for user in users:
+            user_body = User._compose_patch_body(
+                login_id=user.login_id,
+                email=user.email,
+                phone=user.phone,
+                display_name=user.display_name,
+                given_name=user.given_name,
+                middle_name=user.middle_name,
+                family_name=user.family_name,
+                role_names=user.role_names,
+                user_tenants=user.user_tenants,
+                picture=user.picture,
+                custom_attributes=user.custom_attributes,
+                verified_email=user.verified_email,
+                verified_phone=user.verified_phone,
+                sso_app_ids=user.sso_app_ids,
+                status=user.status,
+                test=test,
+            )
+            users_body.append(user_body)
+
+        return {"users": users_body}

descope/mgmt.py

@@ -25,7 +25,7 @@
 class MGMT:
     _http: HTTPClient
 
-    def __init__(self, http_client: HTTPClient):
+    def __init__(self, http_client: HTTPClient, fga_cache_url: str | None = None):
         """Create a management API facade.
 
         Args:
@@ -35,7 +35,7 @@ def __init__(self, http_client: HTTPClient):
         self._access_key = AccessKey(http_client)
         self._audit = Audit(http_client)
         self._authz = Authz(http_client)
-        self._fga = FGA(http_client)
+        self._fga = FGA(http_client, fga_cache_url=fga_cache_url)
         self._flow = Flow(http_client)
         self._group = Group(http_client)
         self._jwt = JWT(http_client)