drf-api-role-permissions 1.0.0

Role-based API and model field permissions for Django REST Framework

drf-api-role-permissions

Role-based access control for Django REST Framework. Assign users to roles, grant API endpoint access by URL name and HTTP method, and restrict model field visibility and object access at the serializer and queryset level.

Features

• API permissions — sync discovered URL patterns and enforce access by url_name + HTTP method
• Model permissions — field-level and object-level restrictions for view, edit, and create actions
• Automatic DRF integration — optional monkey-patches for ModelSerializer and GenericAPIView
• Management API — REST endpoints to manage roles, permissions, and user assignments
• Django admin — manage roles and model permissions from the admin site

Installation

pip install drf-api-role-permissions

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "rest_framework",
    "django_filters",
    "role_permissions",
]

Run migrations:

python manage.py migrate role_permissions

Quick start

1. Wire up URLs

# urls.py
from django.urls import include, path

urlpatterns = [
    path("api/v1/rbac/", include("role_permissions.urls")),
]

2. Enable API permission checks

Every protected endpoint must have a named URL pattern. Then set the default DRF permission class:

REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "role_permissions.permissions.HasAPIRolePermission",
    ],
}

3. Sync API permissions

Discover all named URL routes and store them in the database:

python manage.py sync_api_permissions

4. Assign roles

Use the management API or Django admin to:

1. Create a Role
2. Attach APIPermission and ModelPermission records
3. Assign the role to a user via UserRole

Configuration

Optional settings under RBAC in settings.py:

RBAC = {
    # Auto-patch ModelSerializer and GenericAPIView (default: True)
    "AUTO_PATCH_SERIALIZERS": True,

    # Apps excluded from model/field discovery
    "EXCLUDE_APPS": ["admin", "auth", "contenttypes", "sessions", "messages", "staticfiles", "role_permissions"],

    # URL path regexes excluded from API permission sync
    "EXCLUDE_URL_REGEXES": [r"^admin/.*$", r"^docs/.*$", r"^static/.*$", r"^media/.*$"],

    # Role permission cache TTL in seconds
    "CACHE_TTL": 3600,

    # Fields shown in nested user serializers
    "USER_DETAIL_FIELDS": ("id", "username", "first_name", "last_name", "email"),

    # Pagination class for management API list views
    "PAGINATION_CLASS": "role_permissions.pagination.DefaultLimitOffsetPagination",
}

Middleware (optional)

If serializers are created without request context, enable thread-local request storage:

MIDDLEWARE = [
    # ...
    "role_permissions.middleware.CurrentRequestMiddleware",
]

Serializer integration

Automatic patching (default)

When AUTO_PATCH_SERIALIZERS is enabled, all ModelSerializer instances automatically enforce field permissions, and list/retrieve/update views filter objects by object_ids.

Explicit mixin

Disable auto-patching and use the mixin on specific serializers:

from role_permissions.serializer_mixins import RolePermissionsModelSerializer

class ProductSerializer(RolePermissionsModelSerializer):
    class Meta:
        model = Product
        fields = "__all__"

Opt out per serializer:

class PublicSerializer(RolePermissionsModelSerializer):
    class Meta:
        model = Product
        fields = ("id", "name")
        disable_rbac = True

License

MIT