8. API reference

Axes offers extensible APIs that you can customize to your liking. You can specialize the following base classes or alternatively use third party modules as long as they implement the following APIs.

class axes.handlers.base.AbstractAxesHandler

Contract that all handlers need to follow

abstractmethod get_failures(request, credentials: dict | None = None) → int

Checks the number of failures associated to the given request and credentials.

This is a virtual method that needs an implementation in the handler subclass if the settings.AXES_LOCK_OUT_AT_FAILURE flag is set to True.

abstractmethod user_logged_in(sender, request, user, **kwargs): Handles the Django django.contrib.auth.signals.user_logged_in authentication signal.

abstractmethod user_logged_out(sender, request, user, **kwargs): Handles the Django django.contrib.auth.signals.user_logged_out authentication signal.

abstractmethod user_login_failed(sender, credentials: dict, request=None, **kwargs): Handles the Django django.contrib.auth.signals.user_login_failed authentication signal.

class axes.handlers.base.AxesBaseHandler

Handler API definition for implementations that are used by the AxesProxyHandler.

If you wish to specialize your own handler class, override the necessary methods and configure the class for use by setting settings.AXES_HANDLER = 'module.path.to.YourClass'. Make sure that new the handler is compliant with AbstractAxesHandler and make sure it extends from this mixin. Refer to AxesHandler for an example.

The default implementation that is actually used by Axes is axes.handlers.database.AxesDatabaseHandler.

Note

This is a virtual class and can not be used without specialization.

get_admin_url() → str | None: Returns admin url if exists, otherwise returns None

is_admin_request(request) → bool: Checks that request located under admin site

is_admin_site(request) → bool: Checks if the request is NOT for admin site if settings.AXES_ONLY_ADMIN_SITE is True.

is_allowed(request, credentials: dict | None = None) → bool

Checks if the user is allowed to access or use given functionality such as a login view or authentication.

This method is abstract and other backends can specialize it as needed, but the default implementation checks if the user has attempted to authenticate into the site too many times through the Django authentication backends and returns False if user exceeds the configured Axes thresholds.

This checker can implement arbitrary checks such as IP whitelisting or blacklisting, request frequency checking, failed attempt monitoring or similar functions.

Please refer to the axes.handlers.database.AxesDatabaseHandler for the default implementation and inspiration on some common checks and access restrictions before writing your own implementation.

is_blacklisted(request, credentials: dict | None = None) → bool: Checks if the request or given credentials are blacklisted from access.

is_locked(request, credentials: dict | None = None) → bool: Checks if the request or given credentials are locked.

is_whitelisted(request, credentials: dict | None = None) → bool: Checks if the request or given credentials are whitelisted for access.

remove_out_of_limit_failure_logs(*, username: str, limit: int | None = None) → int

Remove access failure logs that are over AXES_ACCESS_FAILURE_LOG_PER_USER_LIMIT for user username.

This method makes more sense for the DB backend, but as it is used by the ProxyHandler (via inherent), it needs to be defined here, so we get compliant with all proxy methods.

Please overwrite it on each specialized handler as needed.

reset_attempts(*, ip_address: str | None = None, username: str | None = None, ip_or_username: bool = False) → int

Resets access attempts that match the given IP address or username.

This method makes more sense for the DB backend, but as it is used by the ProxyHandler (via inherent), it needs to be defined here, so we get compliant with all proxy methods.

Please overwrite it on each specialized handler as needed.

reset_failure_logs(*, age_days: int | None = None) → int

Resets access failure logs that are older than given number of days.

This method makes more sense for the DB backend, but as it is used by the ProxyHandler (via inherent), it needs to be defined here, so we get compliant with all proxy methods.

Please overwrite it on each specialized handler as needed.

reset_logs(*, age_days: int | None = None) → int

Resets access logs that are older than given number of days.

This method makes more sense for the DB backend, but as it is used by the ProxyHandler (via inherent), it needs to be defined here, so we get compliant with all proxy methods.

Please overwrite it on each specialized handler as needed.

class axes.handlers.base.AxesHandler

Signal bare handler implementation without any storage backend.

get_failures(request, credentials: dict | None = None) → int

Checks the number of failures associated to the given request and credentials.

This is a virtual method that needs an implementation in the handler subclass if the settings.AXES_LOCK_OUT_AT_FAILURE flag is set to True.

user_logged_in(sender, request, user, **kwargs): Handles the Django django.contrib.auth.signals.user_logged_in authentication signal.

user_logged_out(sender, request, user, **kwargs): Handles the Django django.contrib.auth.signals.user_logged_out authentication signal.

user_login_failed(sender, credentials: dict, request=None, **kwargs): Handles the Django django.contrib.auth.signals.user_login_failed authentication signal.

class axes.backends.AxesBackend

Bases: AxesStandaloneBackend, ModelBackend

Axes authentication backend that also inherits from ModelBackend, and thus also performs other functions of ModelBackend such as permissions checks.

Use this class as the first item of AUTHENTICATION_BACKENDS to prevent locked out users from being logged in by the Django authentication flow.

Note

This backend does not log your user in. It monitors login attempts. Authentication is handled by the following backends that are configured in AUTHENTICATION_BACKENDS.

class axes.backends.AxesStandaloneBackend

Bases: object

Authentication backend class that forbids login attempts for locked out users.

Use this class as the first item of AUTHENTICATION_BACKENDS to prevent locked out users from being logged in by the Django authentication flow.

Note

This backend does not log your user in. It monitors login attempts. It also does not run any permissions checks at all. Authentication is handled by the following backends that are configured in AUTHENTICATION_BACKENDS.

class axes.middleware.AxesMiddleware(get_response: Callable)

Middleware that calculates necessary HTTP request attributes for attempt monitoring and maps lockout signals into readable HTTP 403 Forbidden responses.

If a project uses django rest framework then the middleware updates the request and checks whether the limit has been exceeded. It’s needed only for integration with DRF because it uses its own request object.

This middleware recognizes a logout monitoring flag in the request and and uses the axes.helpers.get_lockout_response handler for returning customizable and context aware lockout message to the end user if necessary.

To customize the lockout handling behaviour further, you can subclass this middleware and change the __call__ method to your own liking.

Please see the following configuration flags before customizing this handler:

AXES_LOCKOUT_TEMPLATE,
AXES_LOCKOUT_URL,
AXES_COOLOFF_MESSAGE, and
AXES_PERMALOCK_MESSAGE.