Ratelimit Keys

The key= argument to the decorator takes either a string or a callable.

Common keys

The following string values for key= provide shortcuts to commonly used ratelimit keys:

  • 'ip' - Use the request IP address (i.e. request.META['REMOTE_ADDR'])


    If you are using a reverse proxy, make sure this value is correct or use an appropriate header: value. See the security notes.

  • 'get:X' - Use the value of request.GET['X'].

  • 'post:X' - Use the value of request.POST['X'].

  • 'header:x-x' - Use the value of request.META['HTTP_X_X'].


    The value right of the colon will be translated to all-caps and any dashes will be replaced with underscores, e.g.: x-client-ip => X_CLIENT_IP.

  • 'user' - Use an appropriate value from request.user. Do not use with unauthenticated users.

  • 'user_or_ip' - Use an appropriate value from request.user if the user is authenticated, otherwise use request.META['REMOTE_ADDR'] (see the note above about reverse proxies).

String values

Other string values not from the list above will be treated as the dotted Python path to a callable. See below for more on callables.

Callable values

New in version 0.3.

Changed in version 0.5: Added support for python path to callables.

Changed in version 0.6: Callable was mistakenly only passed the request, now also gets group as documented.

If the value of key= is a callable, or the path to a callable, that callable will be called with two arguments, the group and the request object. It should return a bytestring or unicode object, e.g.:

def my_key(group, request):
    return request.META['REMOTE_ADDR'] + request.user.username