feat: add groups management API

- GET /auth/groups - list groups with search/pagination
- POST /auth/groups/sync-from-authentik - bulk sync from Authentik
- Group model and database migration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

src/auth/controller.py

@@ -11,7 +11,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from src.controllers.base import BaseController
 from src.logging_config import get_logger
 from src.db import get_async_session
-from src.auth.schemas import AuthSyncRequest, AuthSyncResponse, UsersListResponse, BulkSyncResultSchema
+from src.auth.schemas import AuthSyncRequest, AuthSyncResponse, UsersListResponse, BulkSyncResultSchema, GroupsListResponse
 from src.auth.service import AuthService
 
 logger = get_logger(__name__)
@@ -152,6 +152,69 @@ class AuthController(BaseController):
                 logger.error(f"Bulk sync failed: {e}")
                 raise HTTPException(status_code=401, detail=str(e))
 
+        @router.get(
+            "/groups",
+            summary="List all groups",
+            response_model=GroupsListResponse,
+            responses={
+                200: {"description": "List of groups"},
+            },
+        )
+        async def list_groups(
+            search: Optional[str] = Query(None, description="Search by group name"),
+            offset: int = Query(0, ge=0, description="Number of records to skip"),
+            limit: int = Query(50, ge=1, le=100, description="Maximum records to return"),
+            session: AsyncSession = Depends(get_async_session),
+        ) -> GroupsListResponse:
+            """
+            List all groups synced from Authentik
+
+            Returns paginated list of groups with their details.
+            Supports search filtering by name.
+            """
+            service = AuthService(session)
+            items, total = await service.list_groups(
+                search=search,
+                offset=offset,
+                limit=limit,
+            )
+            return GroupsListResponse(items=items, total=total)
+
+        @router.post(
+            "/groups/sync-from-authentik",
+            summary="Bulk sync groups from Authentik",
+            response_model=BulkSyncResultSchema,
+            responses={
+                200: {"description": "Sync completed"},
+                401: {"description": "Authentik API credentials invalid"},
+                503: {"description": "Authentik service unavailable"},
+            },
+        )
+        async def sync_groups_from_authentik(
+            session: AsyncSession = Depends(get_async_session),
+        ) -> BulkSyncResultSchema:
+            """
+            Fetch all groups from Authentik and sync to local database
+
+            This endpoint uses the Authentik admin API to fetch all groups
+            and create/update them in the local database. Requires
+            AUTHENTIK_USERNAME and AUTHENTIK_PASSWORD to be configured.
+
+            Use this to populate groups or to re-sync after changes in Authentik.
+            """
+            service = AuthService(session)
+
+            try:
+                result = await service.bulk_sync_groups_from_authentik()
+                logger.info(
+                    f"Groups bulk sync completed: {result.created} created, "
+                    f"{result.updated} updated, {result.failed} failed"
+                )
+                return result
+            except ValueError as e:
+                logger.error(f"Groups bulk sync failed: {e}")
+                raise HTTPException(status_code=401, detail=str(e))
+
         @router.get(
             "/me",
             summary="Get current user profile",