✨(backend) draft initial Room viewset for external applications

From a security perspective, the list endpoint should be limited to return only
rooms created by the external application. Currently, there is a risk of
exposing public rooms through this endpoint.

I will address this in upcoming commits by updating the room model to track
the source of generation. This will also provide useful information
for analytics.

The API viewset was largely copied and adapted. The serializer was heavily
restricted to return a response more appropriate for external applications,
providing ready-to-use information for their users
(for example, a clickable link).

I plan to extend the room information further, potentially aligning it with the
Google Meet API format. This first draft serves as a solid foundation.

Although scopes for delete and update exist, these methods have not yet been
implemented in the viewset. They will be added in future commits.

src/backend/core/external_api/serializers.py

@@ -2,8 +2,11 @@
 
 # pylint: disable=abstract-method
 
+from django.conf import settings
+
 from rest_framework import serializers
 
+from core import models, utils
 from core.api.serializers import BaseValidationOnlySerializer
 
 OAUTH2_GRANT_TYPE_CLIENT_CREDENTIALS = "client_credentials"
@@ -16,3 +19,55 @@ class ApplicationJwtSerializer(BaseValidationOnlySerializer):
     client_secret = serializers.CharField(write_only=True)
     grant_type = serializers.ChoiceField(choices=[OAUTH2_GRANT_TYPE_CLIENT_CREDENTIALS])
     scope = serializers.CharField(write_only=True)
+
+
+class RoomSerializer(serializers.ModelSerializer):
+    """External API serializer for room data exposed to applications.
+
+    Provides limited, safe room information for third-party integrations:
+    - Secure defaults for room creation (trusted access level)
+    - Computed fields (url, telephony) for external consumption
+    - Filtered data appropriate for delegation scenarios
+    - Tracks creation source for auditing
+
+    Intentionally exposes minimal information to external applications,
+    following the principle of least privilege.
+    """
+
+    class Meta:
+        model = models.Room
+        fields = ["id", "name", "slug", "pin_code", "access_level"]
+        read_only_fields = ["id", "name", "slug", "pin_code", "access_level"]
+
+    def to_representation(self, instance):
+        """Enrich response with application-specific computed fields."""
+        output = super().to_representation(instance)
+        request = self.context.get("request")
+        pin_code = output.pop("pin_code", None)
+
+        if not request:
+            return output
+
+        # Add room URL for direct access
+        if settings.APPLICATION_BASE_URL:
+            output["url"] = f"{settings.APPLICATION_BASE_URL}/{instance.slug}"
+
+        # Add telephony information if enabled
+        if settings.ROOM_TELEPHONY_ENABLED:
+            output["telephony"] = {
+                "enabled": True,
+                "phone_number": settings.ROOM_TELEPHONY_PHONE_NUMBER,
+                "pin_code": pin_code,
+                "default_country": settings.ROOM_TELEPHONY_DEFAULT_COUNTRY,
+            }
+
+        return output
+
+    def create(self, validated_data):
+        """Create room with secure defaults for application delegation."""
+
+        # Set secure defaults
+        validated_data["name"] = utils.generate_room_slug()
+        validated_data["access_level"] = models.RoomAccessLevel.TRUSTED
+
+        return super().create(validated_data)

src/backend/core/external_api/viewsets.py

@@ -9,7 +9,7 @@ from django.core.exceptions import ValidationError
 from django.core.validators import validate_email
 
 import jwt
-from rest_framework import decorators, viewsets
+from rest_framework import decorators, mixins, viewsets
 from rest_framework import (
     exceptions as drf_exceptions,
 )
@@ -20,9 +20,9 @@ from rest_framework import (
     status as drf_status,
 )
 
-from core import models
+from core import api, models
 
-from . import serializers
+from . import authentication, permissions, serializers
 
 logger = getLogger(__name__)
 
@@ -129,3 +129,66 @@ class ApplicationViewSet(viewsets.GenericViewSet):
             },
             status=drf_status.HTTP_200_OK,
         )
+
+
+class RoomViewSet(
+    mixins.CreateModelMixin,
+    mixins.RetrieveModelMixin,
+    mixins.ListModelMixin,
+    viewsets.GenericViewSet,
+):
+    """Application-delegated API for room management.
+
+    Provides JWT-authenticated access to room operations for external applications
+    acting on behalf of users. All operations are scope-based and filtered to the
+    authenticated user's accessible rooms.
+
+    Supported operations:
+    - list: List rooms the user has access to (requires 'rooms:list' scope)
+    - retrieve: Get room details (requires 'rooms:retrieve' scope)
+    - create: Create a new room owned by the user (requires 'rooms:create' scope)
+    """
+
+    authentication_classes = [authentication.ApplicationJWTAuthentication]
+    permission_classes = [
+        api.permissions.IsAuthenticated & permissions.HasRequiredRoomScope
+    ]
+    queryset = models.Room.objects.all()
+    serializer_class = serializers.RoomSerializer
+
+    def list(self, request, *args, **kwargs):
+        """Limit listed rooms to the ones related to the authenticated user."""
+
+        user = self.request.user
+
+        if user.is_authenticated:
+            queryset = (
+                self.filter_queryset(self.get_queryset()).filter(users=user).distinct()
+            )
+        else:
+            queryset = self.get_queryset().none()
+
+        page = self.paginate_queryset(queryset)
+        if page is not None:
+            serializer = self.get_serializer(page, many=True)
+            return self.get_paginated_response(serializer.data)
+
+        serializer = self.get_serializer(queryset, many=True)
+        return drf_response.Response(serializer.data)
+
+    def perform_create(self, serializer):
+        """Set the current user as owner of the newly created room."""
+        room = serializer.save()
+        models.ResourceAccess.objects.create(
+            resource=room,
+            user=self.request.user,
+            role=models.RoleChoices.OWNER,
+        )
+
+        # Log for auditing
+        logger.info(
+            "Room created via application: room_id=%s, user_id=%s, client_id=%s",
+            room.id,
+            self.request.user.id,
+            getattr(self.request.auth, "client_id", "unknown"),
+        )