Add authorization permissions support

Introduce the authorization module with CRUD operations for permissions
including create, list (paginated), get, update (PATCH), and delete.
Register the module on both sync and async clients.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: csrbarber

tests/test_authorization.py

@@ -0,0 +1,172 @@
+from typing import Union
+
+import pytest
+from tests.utils.fixtures.mock_permission import MockPermission
+from tests.utils.list_resource import list_response_of
+from tests.utils.syncify import syncify
+from workos.authorization import AsyncAuthorization, Authorization
+
+
+@pytest.mark.sync_and_async(Authorization, AsyncAuthorization)
+class TestAuthorization:
+    @pytest.fixture(autouse=True)
+    def setup(self, module_instance: Union[Authorization, AsyncAuthorization]):
+        self.http_client = module_instance._http_client
+        self.authorization = module_instance
+
+    @pytest.fixture
+    def mock_permission(self):
+        return MockPermission(id="perm_01ABC").dict()
+
+    @pytest.fixture
+    def mock_permissions(self):
+        permission_list = [
+            MockPermission(id=f"perm_{i}", slug=f"perm-{i}").dict() for i in range(5)
+        ]
+        return {
+            "data": permission_list,
+            "list_metadata": {"before": None, "after": None},
+            "object": "list",
+        }
+
+    @pytest.fixture
+    def mock_permissions_multiple_data_pages(self):
+        permission_list = [
+            MockPermission(id=f"perm_{i}", slug=f"perm-{i}").dict() for i in range(40)
+        ]
+        return list_response_of(data=permission_list)
+
+    def test_create_permission(
+        self, mock_permission, capture_and_mock_http_client_request
+    ):
+        request_kwargs = capture_and_mock_http_client_request(
+            self.http_client, mock_permission, 201
+        )
+
+        permission = syncify(
+            self.authorization.create_permission(
+                slug="documents:read", name="Read Documents"
+            )
+        )
+
+        assert permission.id == "perm_01ABC"
+        assert permission.slug == "documents:read"
+        assert request_kwargs["method"] == "post"
+        assert request_kwargs["url"].endswith("/authorization/permissions")
+        assert request_kwargs["json"] == {
+            "slug": "documents:read",
+            "name": "Read Documents",
+        }
+
+    def test_create_permission_with_description(
+        self, mock_permission, capture_and_mock_http_client_request
+    ):
+        request_kwargs = capture_and_mock_http_client_request(
+            self.http_client, mock_permission, 201
+        )
+
+        syncify(
+            self.authorization.create_permission(
+                slug="documents:read",
+                name="Read Documents",
+                description="Allows reading documents",
+            )
+        )
+
+        assert request_kwargs["json"] == {
+            "slug": "documents:read",
+            "name": "Read Documents",
+            "description": "Allows reading documents",
+        }
+
+    def test_list_permissions(
+        self, mock_permissions, capture_and_mock_http_client_request
+    ):
+        request_kwargs = capture_and_mock_http_client_request(
+            self.http_client, mock_permissions, 200
+        )
+
+        permissions_response = syncify(self.authorization.list_permissions())
+
+        assert request_kwargs["method"] == "get"
+        assert request_kwargs["url"].endswith("/authorization/permissions")
+        assert len(permissions_response.data) == 5
+
+    def test_list_permissions_auto_pagination(
+        self,
+        mock_permissions_multiple_data_pages,
+        test_auto_pagination,
+    ):
+        test_auto_pagination(
+            http_client=self.http_client,
+            list_function=self.authorization.list_permissions,
+            expected_all_page_data=mock_permissions_multiple_data_pages["data"],
+        )
+
+    def test_get_permission(
+        self, mock_permission, capture_and_mock_http_client_request
+    ):
+        request_kwargs = capture_and_mock_http_client_request(
+            self.http_client, mock_permission, 200
+        )
+
+        permission = syncify(self.authorization.get_permission("documents:read"))
+
+        assert permission.id == "perm_01ABC"
+        assert request_kwargs["method"] == "get"
+        assert request_kwargs["url"].endswith(
+            "/authorization/permissions/documents:read"
+        )
+
+    def test_update_permission(
+        self, mock_permission, capture_and_mock_http_client_request
+    ):
+        request_kwargs = capture_and_mock_http_client_request(
+            self.http_client, mock_permission, 200
+        )
+
+        permission = syncify(
+            self.authorization.update_permission("documents:read", name="Updated Name")
+        )
+
+        assert permission.id == "perm_01ABC"
+        assert request_kwargs["method"] == "patch"
+        assert request_kwargs["url"].endswith(
+            "/authorization/permissions/documents:read"
+        )
+        assert request_kwargs["json"] == {"name": "Updated Name"}
+
+    def test_update_permission_with_description(
+        self, mock_permission, capture_and_mock_http_client_request
+    ):
+        request_kwargs = capture_and_mock_http_client_request(
+            self.http_client, mock_permission, 200
+        )
+
+        syncify(
+            self.authorization.update_permission(
+                "documents:read",
+                name="Updated Name",
+                description="Updated description",
+            )
+        )
+
+        assert request_kwargs["json"] == {
+            "name": "Updated Name",
+            "description": "Updated description",
+        }
+
+    def test_delete_permission(self, capture_and_mock_http_client_request):
+        request_kwargs = capture_and_mock_http_client_request(
+            self.http_client,
+            202,
+            headers={"content-type": "text/plain; charset=utf-8"},
+        )
+
+        response = syncify(self.authorization.delete_permission("documents:read"))
+
+        assert response is None
+        assert request_kwargs["method"] == "delete"
+        assert request_kwargs["url"].endswith(
+            "/authorization/permissions/documents:read"
+        )

tests/utils/fixtures/mock_permission.py

@@ -0,0 +1,18 @@
+import datetime
+
+from workos.types.authorization.permission import Permission
+
+
+class MockPermission(Permission):
+    def __init__(self, id: str, slug: str = "documents:read"):
+        now = datetime.datetime.now().isoformat()
+        super().__init__(
+            object="permission",
+            id=id,
+            slug=slug,
+            name="Read Documents",
+            description="Allows reading documents",
+            system=False,
+            created_at=now,
+            updated_at=now,
+        )

workos/_base_client.py

@@ -7,6 +7,7 @@
 from workos.utils._base_http_client import DEFAULT_REQUEST_TIMEOUT
 from workos.utils.http_client import HTTPClient
 from workos.audit_logs import AuditLogsModule
+from workos.authorization import AuthorizationModule
 from workos.directory_sync import DirectorySyncModule
 from workos.events import EventsModule
 from workos.mfa import MFAModule
@@ -65,6 +66,10 @@ def __init__(
             else int(os.getenv("WORKOS_REQUEST_TIMEOUT", DEFAULT_REQUEST_TIMEOUT))
         )
 
+    @property
+    @abstractmethod
+    def authorization(self) -> AuthorizationModule: ...
+
     @property
     @abstractmethod
     def audit_logs(self) -> AuditLogsModule: ...

workos/async_client.py

@@ -2,6 +2,7 @@
 from workos.__about__ import __version__
 from workos._base_client import BaseClient
 from workos.audit_logs import AuditLogsModule
+from workos.authorization import AsyncAuthorization
 from workos.directory_sync import AsyncDirectorySync
 from workos.events import AsyncEvents
 from workos.fga import FGAModule
@@ -45,6 +46,12 @@ def __init__(
             timeout=self.request_timeout,
         )
 
+    @property
+    def authorization(self) -> AsyncAuthorization:
+        if not getattr(self, "_authorization", None):
+            self._authorization = AsyncAuthorization(self._http_client)
+        return self._authorization
+
     @property
     def sso(self) -> AsyncSSO:
         if not getattr(self, "_sso", None):