Questions about TokenVerifySerializer and the BlacklistMixin.blacklist() method

[juanbailon]

Hi, I'm currently working on extending the library and had a couple of questions I’d like to clarify regarding the BlacklistMixin and TokenVerifySerializer.

blacklist() method type-hint

The blacklist() method currently has this signature:

def blacklist(self) -> BlacklistedToken:

However, it actually returns a tuple from get_or_create():

return BlacklistedToken.objects.get_or_create(token=token)

the only place where the created boolean is being use is in a test:
tests/test_token_blacklist.py::TestTokenBlacklist::test_tokens_can_be_manually_blacklisted

blacklisted_token, created = token.blacklist()

My question is whether the desire behaviour is to just return the BlacklistedToken since the boolean value is just use in one test and not in any other parts of the code, or whether the return type hint should just be updated to reflect the actual tuple[BlacklistedToken, bool].

I'm asking because I’m implementing a similar method for blacklisting token families (e.g., blacklist_family()), and I’d like to know if I should follow the same pattern — returning (instance, created) — or just return a model instance.

TokenVerifySerializer token blacklist check

Currently, thevalidate method of the serializer only performs the token blacklist check if the setting BLACKLIST_AFTER_ROTATION is True , this is also mention in Issue #786.

If this is intentional, I’d like to understand the reasoning behind it. It seems inconsistent, since token blacklisting can still be used even when BLACKLIST_AFTER_ROTATION is set to False. So, the serializer should still be able to perform the token blacklist check if a refresh token is passed to it.

so changing the IF stamament check for something like this could solve the issue:

if (
            token.get(api_settings.TOKEN_TYPE_CLAIM) == RefreshToken.token_type
            and "rest_framework_simplejwt.token_blacklist" in settings.INSTALLED_APPS
        ):
            jti = token.get(api_settings.JTI_CLAIM)
            if BlacklistedToken.objects.filter(token__jti=jti).exists():
                raise ValidationError(_("Token is blacklisted"))

And the conditional import of BlacklistedToken at the top of the serializers.py file would need to be updated to a regular import.

Thanks for your time. It would be very helpful to get clarification on these two points.

[sanyamk23]

Hi @juanbailon
Thanks again for the detailed breakdown — just wanted to reevaluate and say I agree with both points.

✅ For blacklist(), updating the return type to tuple[BlacklistedToken, bool] makes total sense. It reflects what’s returned and avoids confusion down the line. If we do decide to drop the boolean later, that can be handled with a cleaner return — but for now, aligning the type hint feels like the right call.

✅ For the blacklist check in TokenVerifySerializer, I think your suggestion improves flexibility without introducing any breaking behavior. It’d allow blacklisting to work independently of rotation settings, which is much more intuitive, also fully on board with the standardization of the BlacklistedToken import.

Happy to follow this direction and contribute if needed. Marking this as resolved from my end — great job bringing this up!

Cheers,
Sanyam