djangorestframework-simplejwt

djangorestframework-simplejwt (Simple JWT) is a JSON Web Token authentication plugin for the Django REST Framework. It replaces DRF’s default session or token authentication with JWT-based access and refresh tokens, issued and validated through a single, pluggable SIMPLE_JWT settings block.

Beyond basic token issuance, it supports refresh token rotation with blacklisting, sliding tokens, stateless (no-database-lookup) authentication, custom claims, and multiple signing algorithms including RSA/ECDSA and remote JWKS key resolution — making it suitable for anything from a single Django monolith to a fleet of services that only need to verify a shared token’s signature.

What You Get

• Ready-to-mount DRF views for obtaining, refreshing, verifying, and blacklisting JWTs
• A JWTAuthentication class you drop straight into DEFAULT_AUTHENTICATION_CLASSES
• An optional token_blacklist Django app with models, migrations, and admin integration for revoked tokens
• Support for both standard access/refresh token pairs and sliding tokens in the same package

Common Use Cases

• Securing DRF APIs consumed by single-page apps and mobile clients
• Stateless authentication across microservices with no shared session store
• Immediate session/token revocation on logout or password change
• Integrating with external identity providers via a remote JWKS endpoint

Under The Hood

Architecture The package is cleanly layered: tokens.py defines the Token base class and its AccessToken/RefreshToken/SlidingToken subclasses that model JWT payload semantics via dict-like __getitem__/__setitem__; backends.py’s TokenBackend isolates the actual cryptographic encode/decode work built on PyJWT; authentication.py supplies the DRF-facing JWTAuthentication class that resolves a validated token into a user; and serializers.py/views.py provide thin, DRF-idiomatic views (TokenObtainPairView, TokenRefreshView, etc.) that simply validate a serializer and return its data. The optional token_blacklist sub-app adds its own OutstandingToken/BlacklistedToken models and migrations for persistent revocation, kept decoupled from the core token logic. Almost everything pluggable (serializer classes, the user-token class, the user-authentication rule) is resolved through a central api_settings object built on DRF’s APISettings pattern with IMPORT_STRINGS, so a consumer can swap in custom behavior without subclassing or forking the library. Because every layer above tokens.py depends on its payload-dict contract, a change to that core abstraction would ripple through serializers, views, and authentication alike.

Tech Stack The library targets Python 3.10+, Django 4.2 through 6.0, and djangorestframework 3.14+, wrapping PyJWT (both 1.7.x and 2.x are supported) for the actual JWT encode/decode work, with an optional cryptography extra enabling RSA/ECDSA algorithms and an optional python-jose extra. Packaging uses setuptools with setuptools_scm for git-tag-derived versioning. The test matrix is driven by tox across the full Python/Django/DRF/PyJWT combination, CI runs on GitHub Actions (test.yml, release.yml, i18n.yml), documentation is built with Sphinx and hosted on Read the Docs, and the project is distributed under Jazzband, the community-owned home for shared-maintenance Django packages.

Code Quality The test suite is extensive — dedicated modules cover authentication, backends, tokens, views, serializers, models, migrations, and the blacklist app, using pytest, pytest-django, pytest-cov, pytest-xdist, and freezegun, with tests/keys.py supplying RSA/EC test keypairs for asymmetric-algorithm coverage and Codecov tracking coverage over time. Type hints are used throughout (PEP 604 unions, typed return values), enforced by mypy plus django-stubs/djangorestframework-stubs, alongside ruff for linting/formatting and pre-commit hooks. Error handling is explicit and typed rather than swallowed, with a dedicated exception hierarchy (TokenError, TokenBackendError, ExpiredTokenError, InvalidToken, AuthenticationFailed) and consistent raise ... from e chaining that preserves the original cause.

API Design Getting started requires minimal boilerplate: add JWTAuthentication to DEFAULT_AUTHENTICATION_CLASSES and wire two URL patterns to TokenObtainPairView/TokenRefreshView to get full JWT auth working. View naming is consistent and predictable across the obtain/refresh/verify/blacklist family, all settings live under one namespaced SIMPLE_JWT dict rather than polluting Django’s global settings, and every customization point (serializers, claims, the user model wrapper) is swappable via an import-string setting instead of requiring a subclass. Documentation on Read the Docs walks through common customization scenarios directly. The library isn’t conceptually novel — it wraps well-understood JWT semantics rather than inventing new mechanisms — but its ergonomics are polished and its extension points land exactly where real-world usage needs them.