{"id":1461,"library":"djangorestframework-simplejwt","title":"Django REST Framework Simple JWT","description":"djangorestframework-simplejwt is a minimal JSON Web Token (JWT) authentication plugin designed for Django REST Framework. It provides a straightforward way to implement JWT-based authentication, including token obtain, refresh, and verification. Currently at version 5.5.1, it maintains an active development pace with regular updates and patches.","status":"active","version":"5.5.1","language":"en","source_language":"en","source_url":"https://github.com/jazzband/djangorestframework-simplejwt","tags":["django","drf","jwt","authentication","security","token"],"install":[{"cmd":"pip install djangorestframework-simplejwt","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for any Django application. Supports >=3.2.","package":"Django","optional":false},{"reason":"Core dependency as it's a plugin for DRF. Supports >=3.12.4.","package":"djangorestframework","optional":false},{"reason":"Used for JWT encoding/decoding. Requires >=2.0.0, <3.0.0.","package":"PyJWT","optional":false}],"imports":[{"note":"Commonly confused with Django REST Framework's built-in authentication classes.","wrong":"from rest_framework.authentication import JWTAuthentication","symbol":"JWTAuthentication","correct":"from rest_framework_simplejwt.authentication import JWTAuthentication"},{"symbol":"TokenObtainPairView","correct":"from rest_framework_simplejwt.views import TokenObtainPairView"},{"symbol":"TokenRefreshView","correct":"from rest_framework_simplejwt.views import TokenRefreshView"},{"symbol":"TokenVerifyView","correct":"from rest_framework_simplejwt.views import TokenVerifyView"},{"symbol":"TokenObtainPairSerializer","correct":"from rest_framework_simplejwt.serializers import TokenObtainPairSerializer"},{"symbol":"RefreshToken","correct":"from rest_framework_simplejwt.tokens import RefreshToken"}],"quickstart":{"code":"import os\nimport datetime\nfrom pathlib import Path\n\n# settings.py\nSECRET_KEY = os.environ.get('DJANGO_SECRET_KEY', 'your-secret-key')\nDEBUG = True\nALLOWED_HOSTS = []\n\nINSTALLED_APPS = [\n    # ... other Django apps\n    'rest_framework',\n    'rest_framework_simplejwt.token_blacklist', # Required for token blacklisting\n]\n\nMIDDLEWARE = [\n    # ...\n]\n\nROOT_URLCONF = 'myproject.urls'\n\nREST_FRAMEWORK = {\n    'DEFAULT_AUTHENTICATION_CLASSES': (\n        'rest_framework_simplejwt.authentication.JWTAuthentication',\n    ),\n}\n\nSIMPLE_JWT = {\n    'ACCESS_TOKEN_LIFETIME': datetime.timedelta(minutes=5),\n    'REFRESH_TOKEN_LIFETIME': datetime.timedelta(days=1),\n    'ROTATE_REFRESH_TOKENS': True, # Set to True to enable automatic blacklisting on refresh\n    'BLACKLIST_AFTER_ROTATION': True,\n    'UPDATE_LAST_LOGIN': False,\n    'ALGORITHM': 'HS256',\n    'SIGNING_KEY': SECRET_KEY,\n    'VERIFYING_KEY': None,\n    'AUDIENCE': None,\n    'ISSUER': None,\n    'JWK_URL': None,\n    'LEEWAY': 0,\n\n    'AUTH_HEADER_TYPES': ('Bearer',),\n    'AUTH_HEADER_NAME': 'HTTP_AUTHORIZATION',\n    'USER_ID_FIELD': 'id',\n    'USER_ID_CLAIM': 'user_id',\n    'USER_AUTHENTICATION_RULE': 'rest_framework_simplejwt.authentication.default_user_authentication_rule',\n\n    'AUTH_TOKEN_CLASSES': ('rest_framework_simplejwt.tokens.AccessToken',),\n    'TOKEN_TYPE_CLAIM': 'token_type',\n    'TOKEN_USER_CLASS': 'rest_framework_simplejwt.models.TokenUser',\n\n    'JTI_CLAIM': 'jti',\n\n    'SLIDING_TOKEN_REFRESH_EXP_CLAIM': 'refresh_exp',\n    'SLIDING_TOKEN_LIFETIME': datetime.timedelta(minutes=5),\n    'SLIDING_TOKEN_REFRESH_LIFETIME': datetime.timedelta(days=1),\n\n    'TOKEN_OBTAIN_PAIR_SERIALIZER': 'rest_framework_simplejwt.serializers.TokenObtainPairSerializer',\n    'TOKEN_REFRESH_SERIALIZER': 'rest_framework_simplejwt.serializers.TokenRefreshSerializer',\n    'TOKEN_VERIFY_SERIALIZER': 'rest_framework_simplejwt.serializers.TokenVerifySerializer',\n    'TOKEN_BLACKLIST_SERIALIZER': 'rest_framework_simplejwt.serializers.TokenBlacklistSerializer',\n    'TOKEN_SLIDING_OBTAIN_SERIALIZER': 'rest_framework_simplejwt.serializers.TokenObtainSlidingSerializer',\n    'TOKEN_SLIDING_REFRESH_SERIALIZER': 'rest_framework_simplejwt.serializers.TokenRefreshSlidingSerializer',\n}\n\n# urls.py\nfrom django.urls import path\nfrom rest_framework_simplejwt.views import (\n    TokenObtainPairView,\n    TokenRefreshView,\n    TokenVerifyView,\n    TokenBlacklistView\n)\n\nurlpatterns = [\n    path('api/token/', TokenObtainPairView.as_view(), name='token_obtain_pair'),\n    path('api/token/refresh/', TokenRefreshView.as_view(), name='token_refresh'),\n    path('api/token/verify/', TokenVerifyView.as_view(), name='token_verify'),\n    path('api/token/blacklist/', TokenBlacklistView.as_view(), name='token_blacklist'),\n]","lang":"python","description":"To quickly set up djangorestframework-simplejwt, first add `rest_framework_simplejwt.token_blacklist` to your `INSTALLED_APPS` if you plan to use token blacklisting (highly recommended). Then, configure `REST_FRAMEWORK` to use `JWTAuthentication` as a default authentication class. Finally, define `SIMPLE_JWT` settings in your `settings.py` and include the token endpoints in your `urls.py`."},"warnings":[{"fix":"If you encounter issues, consider removing any locally generated 0013_blacklist migration files or entries in your `django_migrations` table, then re-running `python manage.py makemigrations` and `python manage.py migrate`.","message":"A missing migration (0013_blacklist) for the `rest_framework_simplejwt.token_blacklist` app was added in v5.5.1. Users who previously ran `makemigrations` on a development branch may have a phantom migration or encounter issues if they created a migration with this name themselves. Carefully review your `django_migrations` table before running `migrate`.","severity":"gotcha","affected_versions":"5.5.1"},{"fix":"Ensure your `PyJWT` version is below 2.10.0. The library's `install_requires` should handle this automatically for new installations, but existing environments may need manual downgrade (`pip install 'PyJWT<2.10.0'`).","message":"Version 5.5.0 introduced a cap on the `PyJWT` dependency, requiring `<2.10.0`. This was done to avoid incompatibility with a subject claim type requirement introduced in newer `PyJWT` versions. Users with `PyJWT` 2.10.0 or higher will experience `TypeError` during token validation.","severity":"breaking","affected_versions":"5.5.0 onwards"},{"fix":"If you rely on automatic refresh token blacklisting for security (e.g., to invalidate old tokens upon refresh), you *must* explicitly set `BLACKLIST_AFTER_ROTATION = True` in your `SIMPLE_JWT` settings.","message":"In version 5.0.0, the default value for `BLACKLIST_AFTER_ROTATION` in `SIMPLE_JWT` settings changed from `True` to `False`. This means refresh tokens are no longer automatically blacklisted after rotation unless explicitly set to `True`.","severity":"breaking","affected_versions":"5.0.0 onwards"},{"fix":"Upgrade your Python, Django, and Django REST Framework versions to currently supported releases (e.g., Python >=3.9, Django >=3.2, DRF >=3.12.4).","message":"With version 5.3.1, support for End-of-Life (EOL) Python, Django, and Django REST Framework versions was removed. While not a breaking change in the library's API, it signifies that installations on older stacks are no longer officially supported and may encounter unpatched issues or unexpected behavior.","severity":"gotcha","affected_versions":"5.3.1 onwards"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}