feat: Support screen_hint in user_management.get_authorization_url

Author: faroceann

tests/test_user_management.py

@@ -13,6 +13,7 @@
 from tests.utils.fixtures.mock_user import MockUser
 from workos.user_management import UserManagement
 from workos.utils.um_provider_types import UserManagementProviderType
+from workos.utils.um_screen_hint_types import UserManagementScreenHintType
 from workos.utils.request import RESPONSE_TYPE_CODE
 
 
@@ -508,6 +509,49 @@ def test_authorization_url_throws_value_error_with_incorrect_provider_type(
                 redirect_uri=redirect_uri,
             )
 
+    @pytest.mark.parametrize(
+        "invalid_screen_hint",
+        [
+            123,
+            UserManagementScreenHintType,
+            True,
+            False,
+            {"screen_hint": "Something"},
+            ["Something"],
+        ],
+    )
+    def test_authorization_url_throws_value_error_with_incorrect_screen_hint_type(
+        self, invalid_screen_hint
+    ):
+        with pytest.raises(
+            ValueError, match="'screen_hint' must be of type UserManagementScreenHintType"
+        ):
+            redirect_uri = "https://localhost/auth/callback"
+            self.user_management.get_authorization_url(
+                screen_hint=invalid_screen_hint,
+                redirect_uri=redirect_uri,
+                provider=UserManagementProviderType.AuthKit
+            )
+
+    def test_authorization_url_has_expected_query_params_with_screen_hint(self):
+        screen_hint = UserManagementScreenHintType.SignUp
+        redirect_uri = "https://localhost/auth/callback"
+        authorization_url = self.user_management.get_authorization_url(
+            screen_hint=screen_hint,
+            redirect_uri=redirect_uri,
+            provider=UserManagementProviderType.AuthKit
+        )
+
+        parsed_url = urlparse(authorization_url)
+
+        assert dict(parse_qsl(parsed_url.query)) == {
+            "screen_hint": screen_hint.value,
+            "client_id": workos.client_id,
+            "redirect_uri": redirect_uri,
+            "response_type": RESPONSE_TYPE_CODE,
+            "provider": UserManagementProviderType.AuthKit.value
+        }
+
     def test_authorization_url_has_expected_query_params_with_connection_id(self):
         connection_id = "connection_123"
         redirect_uri = "https://localhost/auth/callback"

workos/user_management.py

@@ -16,6 +16,7 @@
 )
 from workos.utils.pagination_order import Order
 from workos.utils.um_provider_types import UserManagementProviderType
+from workos.utils.um_screen_hint_types import UserManagementScreenHintType
 from workos.utils.request import (
     RequestHelper,
     RESPONSE_TYPE_CODE,
@@ -424,6 +425,7 @@ def get_authorization_url(
         login_hint=None,
         state=None,
         code_challenge=None,
+        screen_hint=None
     ):
         """Generate an OAuth 2.0 authorization URL.
 
@@ -446,6 +448,7 @@ def get_authorization_url(
             state (str) - An encoded string passed to WorkOS that'd be preserved through the authentication workflow, passed
                 back as a query parameter. (Optional)
             code_challenge (str) - Code challenge is derived from the code verifier used for the PKCE flow. (Optional)
+            screen_hint (UserManagementScreenHintType) - Specify which AuthKit screen users should land on upon redirection (Only applicable when provider is 'authkit').
 
         Returns:
             str: URL to redirect a User to to begin the OAuth workflow with WorkOS
@@ -481,6 +484,13 @@ def get_authorization_url(
         if code_challenge:
             params["code_challenge"] = code_challenge
             params["code_challenge_method"] = "S256"
+        if screen_hint is not None:
+            if not isinstance(screen_hint, UserManagementScreenHintType):
+                raise ValueError(
+                    "'screen_hint' must be of type UserManagementScreenHintType"
+                )
+
+            params["screen_hint"] = screen_hint.value
 
         prepared_request = Request(
             "GET",

workos/utils/um_screen_hint_types.py

@@ -0,0 +1,6 @@
+from enum import Enum
+
+
+class UserManagementScreenHintType(Enum):
+    SignUp = "sign-up"
+    SignIn = "sign-in"