Can Django REST Framework authentication classes fall back after an expired credential raises AuthenticationFailed?

No, Django REST Framework (DRF) does not fall back if an authentication class raises AuthenticationFailed. The sequential evaluation model is designed to stop immediately when an exception is raised, signaling that the provided credentials are explicitly invalid or expired.

To achieve a fallback mechanism for expired credentials, a custom authentication class must explicitly return None instead of raising an exception. In DRF, the authenticate method logic follows these rules:

• Returns a (user, auth) tuple: The chain stops, and the user is authenticated.
• Returns None: The chain continues to the next class in the list.
• Raises AuthenticationFailed: The chain stops and an error is returned to the client.

Recommended Pattern for Token Expiration

Since the default rest_framework.authtoken lacks an expiration field, the most robust way to enforce expiration without modifying core models is to subclass the existing authentication class. This allows you to intercept the validation logic and return None when the token is stale.

pre> from rest_framework.authtoken.authentication import TokenAuthentication from rest_framework.exceptions import AuthenticationFailed from django.utils import timezone import logging logger = logging.getLogger(__name__) class FlexibleTokenAuthentication(TokenAuthentication): EXPIRATION_DAYS = 7 def authenticate(self, request): # Use super to get the token from request credentials = super().authenticate(request) if credentials is None: return None user, token = credentials # Logic to check expiration (requires a 'created_at' field # or a custom field on your token model) if token.created_at < timezone.now() - timedelta(days=self.EXPIRATION_DAYS): logger.warning(f"Expired token used for user {user.id}") # Returning None allows the next class in the list to run return None return (user, token)

Logging and Auditability

When you intentionally decline to authenticate by returning None, you should use Django's logging framework to record the event. This ensures that while the API continues to check for other authentication methods (like a session), the system still maintains an audit trail of the expired-credential attempt.

Note: By returning None, the client will receive a generic 401 error only if all authentication classes fail. If you need to explicitly tell the client specifically that their token is expired, you must raise AuthenticationFailed, which will prevent any fallback behavior.