Welcome to djoser’s documentation!

Introduction

REST implementation of Django authentication system. djoser library provides a set of Django Rest Framework views to handle basic actions such as registration, login, logout, password reset and account activation. It works with custom user model.

Instead of reusing Django code (e.g. PasswordResetForm), we reimplemented few things to fit better into Single Page App architecture.

Developed by SUNSCRAPERS with passion & patience.

Getting started

Available endpoints

  • /me/
  • /users/create/
  • /users/delete/
  • /users/activate/
  • /{{ User.USERNAME_FIELD }}/
  • /password/
  • /password/reset/
  • /password/reset/confirm/
  • /token/create/ (Token Based Authentication)
  • /token/destroy/ (Token Based Authentication)
  • /jwt/create/ (JSON Web Token Authentication)
  • /jwt/refresh/ (JSON Web Token Authentication)
  • /jwt/verify/ (JSON Web Token Authentication)

Supported authentication backends

Supported Python versions

  • Python 2.7
  • Python 3.4
  • Python 3.5
  • Python 3.6

Supported Django versions

  • Django 1.10
  • Django 1.11

Supported Django Rest Framework versions

  • Django Rest Framework 3.7

Installation

$ pip install -U djoser

If you are going to use JWT authentication, you will also need to install django-rest-framework-jwt with:

$ pip install -U djangorestframework-jwt

Configuration

Configure INSTALLED_APPS:

INSTALLED_APPS = (
    'django.contrib.auth',
    (...),
    'rest_framework',
    'djoser',
    (...),
)

Configure urls.py:

urlpatterns = [
    (...),
    url(r'^auth/', include('djoser.urls')),
]

HTTP Basic Auth strategy is assumed by default as Django Rest Framework does it. We strongly discourage and do not provide any explicit support for basic auth. You should customize your authentication backend as described in Authentication Backends.

Sample usage

We provide a standalone test app for you to start easily, see how everything works with basic settings. It might be useful before integrating djoser into your backend application.

In this extremely short tutorial we are going to mimic the simplest flow: register user, log in and log out. We will also check resource access on each consecutive step. Let’s go!

Clone repository and install djoser to your virtualenv:

$ git clone git@github.com:sunscrapers/djoser.git
$ cd djoser
$ pip install -e .

Go to the testproject directory, migrate the database and start the development server:

$ cd testproject
$ ./manage.py migrate
$ ./manage.py runserver 8088

Register a new user:

$ curl -X POST http://127.0.0.1:8088/auth/users/create/ --data 'username=djoser&password=djoser'
{"email": "", "username": "djoser", "id":1}

So far, so good. We have just created a new user using REST API.

Let’s access user’s details:

$ curl -X GET http://127.0.0.1:8088/auth/me/
{"detail": "Authentication credentials were not provided."}

As we can see, we cannot access user profile without logging in. Pretty obvious.

Let’s log in:

curl -X POST http://127.0.0.1:8088/auth/token/create/ --data 'username=djoser&password=djoser'
{"auth_token": "b704c9fc3655635646356ac2950269f352ea1139"}

We have just obtained an authorization token that we may use later in order to retrieve specific resources.

Let’s access user’s details again:

$ curl -X GET http://127.0.0.1:8088/auth/me/
{"detail": "Authentication credentials were not provided."}

Access is still forbidden but let’s offer the token we obtained:

$ curl -X GET http://127.0.0.1:8088/auth/me/ -H 'Authorization: Token b704c9fc3655635646356ac2950269f352ea1139'
{"email": "", "username": "djoser", "id": 1}

Yay, it works!

Now let’s log out:

curl -X POST http://127.0.0.1:8088/auth/token/destroy/ -H 'Authorization: Token b704c9fc3655635646356ac2950269f352ea1139'

And try access user profile again:

$ curl -X GET http://127.0.0.1:8088/auth/me/ -H 'Authorization: Token b704c9fc3655635646356ac2950269f352ea1139'
{"detail": "Invalid token"}

As we can see, user has been logged out successfully and the proper token has been removed.

Authentication Backends

Note

Both Token Based and JWT Authentication can coexist at same time. Simply, follow instructions for both authentication methods and it should work.

Token Based Authentication

Add 'rest_framework.authtoken' to INSTALLED_APPS:

INSTALLED_APPS = [
    'django.contrib.auth',
    (...),
    'rest_framework',
    'rest_framework.authtoken',
    'djoser',
    (...),
]

Configure urls.py. Pay attention to djoser.url.authtoken module path:

urlpatterns = [
    (...),
    url(r'^auth/', include('djoser.urls.authtoken')),
]

Add rest_framework.authentication.TokenAuthentication to Django REST Framework authentication strategies tuple:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework.authentication.TokenAuthentication',
        (...)
    ),
}

Run migrations - this step will create tables for auth and authtoken apps:

$ ./manage.py migrate

JSON Web Token Authentication

Configure urls.py with djoser.url.jwt module path:

urlpatterns = [
    (...),
    url(r'^auth/', include('djoser.urls.jwt')),
]

Add rest_framework_jwt.authentication.JSONWebTokenAuthentication to Django REST Framework authentication strategies tuple:

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': (
        'rest_framework_jwt.authentication.JSONWebTokenAuthentication',
        (...)
    ),
}

Settings

You may optionally provide DJOSER settings:

DJOSER = {
    'PASSWORD_RESET_CONFIRM_URL': '#/password/reset/confirm/{uid}/{token}',
    'ACTIVATION_URL': '#/activate/{uid}/{token}',
    'SEND_ACTIVATION_EMAIL': True,
    'SERIALIZERS': {},
}

PASSWORD_RESET_CONFIRM_URL

URL to your frontend password reset page. It should contain {uid} and {token} placeholders, e.g. #/password-reset/{uid}/{token}. You should pass uid and token to reset password confirmation endpoint.

Required: True

SEND_ACTIVATION_EMAIL

If True user will be required to click activation link sent in email after:

  • creating an account via RegistrationView
  • updating his email via UserView

Default: False

SEND_CONFIRMATION_EMAIL

If True, register or activation endpoint will send confirmation email to user.

Default: False

ACTIVATION_URL

URL to your frontend activation page. It should contain {uid} and {token} placeholders, e.g. #/activate/{uid}/{token}. You should pass uid and token to activation endpoint.

Required: True

SET_USERNAME_RETYPE

If True, you need to pass re_new_{{ User.USERNAME_FIELD }} to /{{ User.USERNAME_FIELD }}/ endpoint, to validate username equality.

Default: False

SET_PASSWORD_RETYPE

If True, you need to pass re_new_password to /password/ endpoint, to validate password equality.

Default: False

PASSWORD_RESET_CONFIRM_RETYPE

If True, you need to pass re_new_password to /password/reset/confirm/ endpoint in order to validate password equality.

Default: False

LOGOUT_ON_PASSWORD_CHANGE

If True, setting new password will logout the user.

Default: False

USER_EMAIL_FIELD_NAME

Determines which field in User model is used for email in versions of Django before 1.11. In Django 1.11 and greater value of this setting is ignored and value provided by User.get_email_field_name is used. This setting will be dropped when Django 1.8 LTS goes EOL.

Default: 'email'

PASSWORD_RESET_SHOW_EMAIL_NOT_FOUND

If True, posting a non-existent email to /password/reset/ will return a HTTP_400_BAD_REQUEST response with an EMAIL_NOT_FOUND error message (‘User with given email does not exist.’).

If False (default), the /password/reset/ endpoint will always return a HTTP_204_NO_CONTENT response.

Please note that setting this to True will expose information whether an email is registered in the system.

Default: False

TOKEN_MODEL

Points to which token model should be used for authentication.

Example: 'knox.models.AuthToken' Default: 'rest_framework.authtoken.models.Token'

SERIALIZERS

This dictionary is used to update the defaults, so by providing, let’s say, one key, all the others will still be used.

Examples

{
    'user': 'myapp.serializers.SpecialUserSerializer',
}

Default:

{
   'activation': 'djoser.serializers.ActivationSerializer',
    'password_reset': 'djoser.serializers.PasswordResetSerializer',
    'password_reset_confirm': 'djoser.serializers.PasswordResetConfirmSerializer',
    'password_reset_confirm_retype': 'djoser.serializers.PasswordResetConfirmRetypeSerializer',
    'set_password': 'djoser.serializers.SetPasswordSerializer',
    'set_password_retype': 'djoser.serializers.SetPasswordRetypeSerializer',
    'set_username': 'djoser.serializers.SetUsernameSerializer',
    'set_username_retype': 'djoser.serializers.SetUsernameRetypeSerializer',
    'user_create': 'djoser.serializers.UserCreateSerializer',
    'user_delete': 'djoser.serializers.UserDeleteSerializer',
    'user': 'djoser.serializers.UserSerializer',
    'token': 'djoser.serializers.TokenSerializer',
    'token_create': 'djoser.serializers.TokenCreateSerializer',
}

Base Endpoints

User

Use this endpoint to retrieve/update user.

Default URL: /me/

Method Request Response
GET –

HTTP_200_OK

  • {{ User.USERNAME_FIELD }}
  • {{ User._meta.pk.name }}
  • {{ User.REQUIRED_FIELDS }}
PUT {{ User.REQUIRED_FIELDS }}

HTTP_200_OK

  • {{ User.USERNAME_FIELD }}
  • {{ User._meta.pk.name }}
  • {{ User.REQUIRED_FIELDS }}

User Create

Use this endpoint to register new user. Your user model manager should implement create_user method and have USERNAME_FIELD and REQUIRED_FIELDS fields.

Default URL: /users/create/

Method Request Response
POST
  • {{ User.USERNAME_FIELD }}
  • {{ User.REQUIRED_FIELDS }}
  • password

HTTP_201_CREATED

  • {{ User.USERNAME_FIELD }}
  • {{ User._meta.pk.name }}
  • {{ User.REQUIRED_FIELDS }}

User Delete

Use this endpoint to delete authenticated user. By default it will simply verify password provided in current_password, delete the auth token if token based authentication is used and invoke delete for a given User instance. One of ways to customize the delete behavior is to override User.delete.

Default URL: /users/delete/

Method Request Response
POST
  • current_password

HTTP_204_NO_CONTENT

HTTP_400_BAD_REQUEST

  • current_password

User Activate

Use this endpoint to activate user account. This endpoint is not a URL which will be directly exposed to your users - you should provide site in your frontend application (configured by ACTIVATION_URL) which will send POST request to activate endpoint.

Default URL: /users/activate/

Method Request Response
POST
  • uid
  • token
 HTTP_204_NO_CONTENT

Set Username

Use this endpoint to change user username (USERNAME_FIELD).

Default URL: /{{ User.USERNAME_FIELD }}/

Note

re_new_{{ User.USERNAME_FIELD }} is only required if SET_USERNAME_RETYPE is True

Method Request Response
POST
  • new_{{ User.USERNAME_FIELD }}
  • re_new_{{ User.USERNAME_FIELD }}
  • current_password
 HTTP_204_NO_CONTENT

Set Password

Use this endpoint to change user password.

Default URL: /password/

Note

re_new_password is only required if SET_PASSWORD_RETYPE is True

Method Request Response
POST
  • new_password
  • re_new_password
  • current_password
 HTTP_204_NO_CONTENT

Reset Password

Use this endpoint to send email to user with password reset link. You have to setup PASSWORD_RESET_CONFIRM_URL.

Default URL: /password/reset/

Note

HTTP_204_NO_CONTENT if PASSWORD_RESET_SHOW_EMAIL_NOT_FOUND is False

Otherwise and if email does not exist in database HTTP_400_BAD_REQUEST

Method Request Response
POST email
  • HTTP_204_NO_CONTENT
  • HTTP_400_BAD_REQUEST

Reset Password Confirmation

Use this endpoint to finish reset password process. This endpoint is not a URL which will be directly exposed to your users - you should provide site in your frontend application (configured by PASSWORD_RESET_CONFIRM_URL) which will send POST request to reset password confirmation endpoint.

Default URL: /password/reset/confirm/

Note

re_new_password is only required if PASSWORD_RESET_CONFIRM_RETYPE is True

Method Request Response
POST
  • uid
  • token
  • new_password
  • re_new_password
 HTTP_204_NO_CONTENT

Token Endpoints

Token Create

Use this endpoint to obtain user authentication token. This endpoint is available only if you are using token based authentication.

Default URL: /token/create/

Method Request Response
POST
  • {{ User.USERNAME_FIELD }}
  • password

HTTP_200_OK

  • auth_token

Token Destroy

Use this endpoint to logout user (remove user authentication token). This endpoint is available only if you are using token based authentication.

Default URL: /token/destroy/

Method Request Response
POST – HTTP_204_NO_CONTENT

JWT Endpoints

JWT Create

Use this endpoint to obtain JWT.

Default URL: /jwt/create/

Method Request Response
POST
  • token

HTTP_200_OK

  • token

HTTP_400_BAD_REQUEST

  • non_field_errors

JWT Refresh

Use this endpoint to refresh JWT.

Default URL: /jwt/refresh/

Method Request Response
POST
  • token

HTTP_200_OK

  • token

HTTP_400_BAD_REQUEST

  • non_field_errors

JWT Verify

Use this endpoint to verify JWT.

Default URL: /jwt/verify/

Method Request Response
POST
  • token

HTTP_200_OK

  • token

HTTP_400_BAD_REQUEST

  • non_field_errors

Emails

Explicit email support has been removed from djoser in 0.8.0. It didn’t make sense to handle such responsibility in a package, which should simply provide an implementation of common authentication-related REST endpoints.

Email support is now handled with the django-templated-mail package.

Adjustment

If you need to customize any serializer behaviour you can use the DJOSER['SERIALIZERS'] setting to use your own serializer classes in the built-in views. Or if you need to completely change the default djoser behaviour, you can always override djoser views with your own custom ones.

Define custom urls instead of reusing djoser.urls:

urlpatterns = patterns('',
    (...),
    url(r'^register/$', views.CustomRegistrationView.as_view()),
)

Define custom view/serializer (inherit from one of djoser class) and override necessary method/field:

class CustomRegistrationView(djoser.views.RegistrationView):

    def send_activation_email(self, *args, **kwargs):
        your_custom_email_sender(*args, **kwargs)

You could check djoser API in source code:

Examples

Early detecting invalid password reset tokens

When there is need to check if password reset token is still valid without actually resetting the password it is possible to approach the problem like so:

from django.contrib.auth.tokens import default_token_generator
from rest_framework import generics, permissions, status
from rest_framework.response import Response

from djoser import serializers


class PasswordTokenCheckView(generics.CreateAPIView):
    permission_classes = (
        permissions.AllowAny,
    )
    token_generator = default_token_generator
    serializer_class = serializers.UidAndTokenSerializer

    def post(self, request, *args, **kwargs):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        headers = self.get_success_headers(serializer.data)
        return Response(serializer.data, status=status.HTTP_200_OK, headers=headers)

Indices and tables