Object-Level Permissions

The Foundation: The owner Field

Before you can check if a user is the owner of an object, the object's model needs to know who its owner is! This typically involves two key steps:

1. Adding an owner field to your model: This is usually a ForeignKey relationship to Django's built-in User model.
2. Associating the user on creation: When a new object is created via the API, you need to automatically assign the currently authenticated user to the owner field.

The official Django REST Framework tutorial provides the canonical guide for this.

With this setup in place, every object will be tied to a user, paving the way for ownership checks.

Approach 1: The IsOwnerOrReadOnly Custom Permission

This is the most common and direct way to handle object-level permissions in DRF. The logic is simple:

• If the request is a "safe" one (like GET), allow it.
• If it's a write request (like PUT or DELETE), only allow it if the requesting user is the object's owner.

The key to this is the has_object_permission method, which, unlike has_permission, is passed the actual object (obj) being requested.

Let's see how to build this permission class.

To see this implemented in a real-world scenario, the video from our previous lesson provides an excellent walkthrough.

This custom class approach is perfect for many common use cases, especially those centered around a single "owner" of an object.

# In permissions.py

from rest_framework import permissions

class IsOwnerOrStaffOrReadOnly(permissions.BasePermission):
    """
    Custom permission to only allow owners of an object or staff to edit it.
    """
    def has_object_permission(self, request, view, obj):
        # Read permissions are allowed to any request,
        # so we'll always allow GET, HEAD or OPTIONS requests.
        if request.method in permissions.SAFE_METHODS:
            return True

        # Write permissions are allowed to the owner of the snippet
        # or to any staff user.
        return obj.owner == request.user or request.user.is_staff

Approach 2: Advanced Control with django-guardian

The IsOwnerOrReadOnly pattern is powerful, but it has limits. What if you need to grant a specific user permission to edit just one document they don't own? Or grant a "Reviewers" group permission to view a single, specific draft article?

This requires a system that can assign permissions on a per-object basis. While you could build a complex system for this yourself using ManyToManyFields, a fantastic third-party package called django-guardian provides this functionality out of the box.

django-guardian integrates with Django's built-in permission framework but allows you to attach those permissions to individual object instances, not just to the entire model.

Let's see how to set it up and use it.

Integrating django-guardian with DRF

The beauty of django-guardian is that it works seamlessly with DRF. DRF has a built-in permission class, DjangoObjectPermissions, which is designed specifically for this purpose.

When you add permissions.DjangoObjectPermissions to a view's permission_classes, its has_object_permission method automatically calls user.has_perm(perm, obj) for you. This means django-guardian's object-level permission checks are automatically applied to your API endpoints.

# In a views.py file
from rest_framework import generics, permissions
from .models import Document
from .serializers import DocumentSerializer

class DocumentDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = Document.objects.all()
    serializer_class = DocumentSerializer
    # This class will use django-guardian's backend automatically!
    permission_classes = [permissions.DjangoObjectPermissions]

Conclusion

You now have a powerful and flexible toolkit for managing permissions in your APIs.

Key Takeaways:

• Object-level permissions control access to specific model instances, not just entire views.
• The essential prerequisite for ownership checks is an owner field on your model, which is typically populated using perform_create in the view.
• The IsOwnerOrReadOnly custom permission class is the standard DRF pattern for simple ownership-based rules, relying on the has_object_permission method.
• For complex scenarios requiring per-object, per-user/group assignments, django-guardian is the industry-standard solution.
• django-guardian provides the assign_perm function to grant permissions and get_objects_for_user to filter querysets. DRF's DjangoObjectPermissions class integrates with it automatically.

Preview of the Next Lesson:
In our next module, we'll shift our focus to The Django Admin Interface. You'll learn how to register your models to get a powerful, auto-generated back-office for managing your application's data. We'll explore how to customize this interface to make it more user-friendly and efficient for data entry and moderation.