Djoser (Django REST Authentication)

2.3.3 · active · verified Thu Apr 16

Djoser provides a set of Django Rest Framework views to handle basic actions such as registration, login, logout, password reset, and account activation. It handles user authentication for Django REST Framework APIs, supporting various authentication backends including Token and JWT. The current version is 2.3.3, and it maintains an active release cadence with regular updates to support new Django and Python versions.

Common errors

```
ModuleNotFoundError: No module named 'djoser'
```
cause Djoser library is not installed or not available in the current Python environment.

fix Run `pip install djoser` to install the library.
```
ImproperlyConfigured: AUTH_USER_MODEL refers to model '...' which has not been installed yet.
```
cause The Django application containing your `AUTH_USER_MODEL` or `djoser`/`rest_framework` itself is missing from `INSTALLED_APPS` in `settings.py`.

fix Ensure `rest_framework`, `djoser`, and the Django app containing your custom user model are listed in `INSTALLED_APPS`.
```
NoReverseMatch at /auth/users/ Reverse for '...' not found. '...' is not a valid view function or pattern name.
```
cause Djoser's URLs are not correctly included in your project's main `urls.py`.

fix Verify that your project's `urls.py` includes `path('auth/', include('djoser.urls'))` and potentially `path('auth/', include('djoser.urls.jwt'))` or `djoser.urls.authtoken` depending on your authentication method.
```
TypeError: __init__() got an unexpected keyword argument 'ID_FIELD'
```
cause Your custom Djoser serializer or settings still refers to the deprecated `ID_FIELD` parameter.

fix Update your `DJOSER` settings or custom serializer code to use `USER_ID_FIELD` instead of `ID_FIELD`.

Warnings

breaking Djoser 2.3.0 introduced a vulnerability fix that requires users to have correctly configured `AUTHENTICATION_BACKENDS` in their Django settings for authentication to succeed. If your setup previously worked without a proper backend, it might break.
Fix: Ensure your `settings.py` includes the correct `AUTHENTICATION_BACKENDS` configuration, e.g., `AUTHENTICATION_BACKENDS = ['django.contrib.auth.backends.ModelBackend']` for default Django users.
breaking Djoser 2.2.0 dropped support for Django 2.x and Python 3.7. Attempting to run Djoser 2.2.0 or higher with these older versions will lead to compatibility issues or errors.
Fix: Upgrade your Django project to Django 3.2+ and your Python environment to Python 3.8+.
breaking In Djoser 2.2.0, the setting `ID_FIELD` was renamed to `USER_ID_FIELD`. Custom serializers or code that directly referenced `ID_FIELD` will encounter `AttributeError` or `TypeError`.
Fix: Update any custom code or `DJOSER` settings that use `ID_FIELD` to `USER_ID_FIELD`.
gotcha Djoser 2.3.2 temporarily introduced a bug that could restrict Django installations to versions lower than 4.0, despite official support for newer Django versions. This was reverted in 2.3.3.
Fix: If experiencing Django version conflicts, ensure you are using Djoser 2.3.3 or later. Downgrade to 2.3.1 if issues persist and upgrading is not an immediate option.
gotcha As of Djoser 2.3.1, `django-templated-mail` was removed from its direct dependencies. If your email customizations explicitly relied on this package, ensure it is installed separately in your project.
Fix: If your project's email logic depends on `django-templated-mail`, explicitly add `pip install django-templated-mail` to your project's requirements.

Install

pip install djoser Install Djoser
pip install djoser[jwt] Install Djoser with JWT support
pip install djoser[social] Install Djoser with social authentication support

Imports

DJOSER_SETTINGS

from djoser.conf import settings as djoser_settings

UserCreateSerializer

from djoser.serializers import UserCreateSerializer

urlpatterns
```
from djoser.urls import urlpatterns
```
Commonly included directly in a project's `urls.py` via `include('djoser.urls')`.
ActivationEmail
```
from djoser.email import ActivationEmail
```
Used when customizing email templates/logic.

Quickstart

To integrate Djoser, first add `rest_framework` and `djoser` to your `INSTALLED_APPS`. Configure `AUTH_USER_MODEL` to point to your desired user model. Define `REST_FRAMEWORK` and `DJOSER` settings in your `settings.py` for authentication classes, permissions, and Djoser-specific URLs and serializers. For JWT, install `djangorestframework-simplejwt` and include `djoser.urls.jwt`. Finally, include Djoser's URLs in your project's `urls.py`.

import os
from datetime import timedelta

# settings.py

INSTALLED_APPS = [
    # ... other Django apps
    'rest_framework',
    'djoser',
    # 'rest_framework_simplejwt', # Required for JWT support
    # 'your_app_name', # If using a custom user model in 'your_app_name'
]

# Point to your custom User model or Django's default
AUTH_USER_MODEL = 'auth.User' # Or 'your_app_name.CustomUser'

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_simplejwt.authentication.JWTAuthentication',
        # 'rest_framework.authentication.TokenAuthentication', # If using Token Auth
        'rest_framework.authentication.SessionAuthentication',
    ),
    'DEFAULT_PERMISSION_CLASSES': (
        'rest_framework.permissions.IsAuthenticatedOrReadOnly',
    ),
}

DJOSER = {
    'PASSWORD_RESET_CONFIRM_URL': '#/password/reset/confirm/{uid}/{token}',
    'USERNAME_RESET_CONFIRM_URL': '#/username/reset/confirm/{uid}/{token}',
    'ACTIVATION_URL': '#/activate/{uid}/{token}',
    'SEND_ACTIVATION_EMAIL': True,
    'SEND_CONFIRMATION_EMAIL': True,
    'SET_PASSWORD_RETYPE': True,
    'SET_USERNAME_RETYPE': True,
    'PASSWORD_RESET_SHOW_EMAIL_NOT_FOUND': True,
    'TOKEN_MODEL': None, # Use Simple JWT by default
    'SERIALIZERS': {
        'user_create': 'djoser.serializers.UserCreateSerializer',
        'user': 'djoser.serializers.UserSerializer',
        'current_user': 'djoser.serializers.UserSerializer',
        'user_delete': 'djoser.serializers.UserDeleteSerializer',
    },
    'EMAIL': {
        'activation': 'djoser.email.ActivationEmail',
        'confirmation': 'djoser.email.ConfirmationEmail',
        'password_reset': 'djoser.email.PasswordResetEmail',
        'password_changed': 'djoser.email.PasswordChangedEmail',
        'username_reset': 'djoser.email.UsernameResetEmail',
        'username_changed': 'djoser.email.UsernameChangedEmail',
    },
}

# For development, print emails to console
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'

# Simple JWT settings (if using JWT authentication)
SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=60),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=1),
    'ROTATE_REFRESH_TOKENS': True,
    'BLACKLIST_AFTER_ROTATION': True,
    'UPDATE_LAST_LOGIN': True,
}

# urls.py (in your project's root)

# from django.contrib import admin
# from django.urls import path, include

# urlpatterns = [
#     path('admin/', admin.site.urls),
#     path('auth/', include('djoser.urls')),
#     path('auth/', include('djoser.urls.jwt')), # For JWT authentication
#     # path('auth/', include('djoser.urls.authtoken')), # For Token authentication
#     # path('auth/', include('djoser.urls.social')), # For social authentication (if installed)
# ]

view raw JSON →