djangorestframework-simplejwt

Simple JWT uses a token_type claim (customizable via TOKEN_TYPE_CLAIM) in the token payload to distinguish between types.

Supported types include:

• access: The default type used to prove authentication.
• sliding: A token that contains both an expiration claim and a refresh expiration claim.
• refresh: Used for obtaining new tokens, but not considered valid for direct authentication.

By default, Simple JWT expects an access token for authentication. You can control which token types are allowed for authentication by configuring the AUTH_TOKEN_CLASSES setting.

You can install Simple JWT using pip. If you need to use digital signature algorithms like RSA or ECDSA, it is recommended to install the [crypto] extra to include the cryptography library automatically. This ensures the dependency is correctly tracked in your requirements files.

Standard installation:

pip install djangorestframework-simplejwt

Installation with cryptographic support (recommended for RSA/ECDSA):

pip install djangorestframework-simplejwt[crypto]

To ensure compatibility across multiple Python versions, use tox. This requires pyenv to manage Python versions.

1. Install the required Python minor versions using pyenv.
2. Create a .python-version file in the project directory containing the version(s) you wish to test against.
3. Run tox to execute the test suite in all configured environments.

To use Simple JWT, you must add rest_framework_simplejwt.authentication.JWTAuthentication to your Django REST Framework authentication classes in settings.py.

If you want to use localizations and translations, also add 'rest_framework_simplejwt' to your INSTALLED_APPS list.

REST_FRAMEWORK = {
    ...
    'DEFAULT_AUTHENTICATION_CLASSES': (
        ...
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    )
    ...
}

INSTALLED_APPS = [
    ...
    'rest_framework_simplejwt',
    ...
]

After creating a custom serializer subclass, you must tell djangorestframework-simplejwt to use it instead of the default by updating the SIMPLE_JWT configuration dictionary in your Django settings.py. Use the TOKEN_OBTAIN_SERIALIZER key with the full Python path to your serializer class.

# Django project settings.py
...

SIMPLE_JWT = {
    # It will work instead of the default serializer(TokenObtainPairSerializer).
    "TOKEN_OBTAIN_SERIALIZER": "my_app.serializers.MyTokenObtainPairSerializer",
    # ...
}

To add custom claims to the JWTs generated by TokenObtainPairView or TokenObtainSlidingView, you must subclass the corresponding serializer and override the get_token class method.

Note that claims added via get_token will be present in both the refresh and access tokens, because the access token is derived from the refresh token produced by this method.

from rest_framework_simplejwt.serializers import TokenObtainPairSerializer
from rest_framework_simplejwt.views import TokenObtainPairView

class MyTokenObtainPairSerializer(TokenObtainPairSerializer):
    @classmethod
    def get_token(cls, user):
        token = super().get_token(user)

        # Add custom claims
        token['name'] = user.name
        # ...

        return token

To develop on Simple JWT, fork the repository on GitHub and clone it locally. Create and activate a virtual environment, then install the package in editable mode with the development dependencies using pip install -e .[dev].

Note for Mac/zsh users: You must escape the brackets in the install command.

pip install --upgrade pip setuptools
pip install -e .[dev]

# For Mac/zsh users:
pip install -e .\[dev\]

To implement stateless user authentication where the backend does not perform a database lookup for a user instance, use the JWTStatelessUserAuthentication backend. Instead of a database record, the authenticate method returns a rest_framework_simplejwt.models.TokenUser instance, which is backed only by a validated token. This is useful for Single Sign-On (SSO) across separately hosted Django applications that share the same token secret key.

Note: In version 5.1.0, JWTTokenUserAuthentication was renamed to JWTStatelessUserAuthentication, but both names remain supported for backwards compatibility.

REST_FRAMEWORK = {
    ...
    'DEFAULT_AUTHENTICATION_CLASSES': (
        ...
        'rest_framework_simplejwt.authentication.JWTStatelessUserAuthentication',
    )
    ...
}

To enable token blacklist functionality, add rest_framework_simplejwt.token_blacklist to your INSTALLED_APPS in settings.py and run the migrations.

When enabled, Simple JWT automatically tracks generated refresh or sliding tokens in an outstanding tokens list and validates them against the blacklist before considering them valid.

# Django project settings.py

INSTALLED_APPS = (
    ...
    'rest_framework_simplejwt.token_blacklist',
    ...
)