Django Quickstart

This guide will help you integrate Descope's Python SDK into your Django application. Follow the steps below to get started.

Install Backend SDK

Install the SDK with the following command:

Terminal
pip install django-descope

Import and Setup Backend SDK

You'll need install and setup all of the packages from the SDK. This is done by ensuring django_descope is under INSTALLED_APPS in settings.py.

If you're using a CNAME with your Descope project, make sure to export the Base URL (e.g. export DESCOPE_BASE_URI="https://api.descope.com") when initializing descope_client.

Optionally, to make the Descope username populate from a custom claim instead of sub, set the DESCOPE_USERNAME_CLAIM to the corresponding username claim in the JWT.

settings.py
INSTALLED_APPS = [
  ...
  'django_descope',
]
DESCOPE_PROJECT_ID=os.getenv("DESCOPE_PROJECT_ID")
DESCOPE_USERNAME_CLAIM=os.getenv("DESCOPE_USERNAME_CLAIM")

Add Descope Middleware

Ensure Descope Middleware is after the AuthenticationMiddleware and SessionMiddleware.

settings.py
MIDDLEWARE = [
  ...
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.contrib.auth.middleware.AuthenticationMiddleware',
  ...
  'django_descope.middleware.DescopeMiddleware',
]

Configure URLconf

You will then need to include the Descope URLconf in your project urls.py like this.

urls.py
path('auth/', include('django_descope.urls')),

Configure URLconf

The session validation is handled in the Django SDK, through the middleware.

settings.py
INSTALLED_APPS = [
  ...
  'django_descope',
]
MIDDLEWARE = [
  ...
  'django.contrib.sessions.middleware.SessionMiddleware',
  'django.contrib.auth.middleware.AuthenticationMiddleware',
  ...
  'django_descope.middleware.DescopeMiddleware',
]
DESCOPE_PROJECT_ID=os.getenv("DESCOPE_PROJECT_ID")

If you're interested in offline JWT validation, check out our offline JWT validation guide.

Implement Session Validation

You will need to then fetch the session token from the Authorization header of each request, and use the SDK to validate the token.

The frontend SDK will store the session token in either a cookie or your browser's local storage. If using a cookie, the token will be sent to your app server automatically with every request.

middleware.py
from django.http import HttpResponseForbidden
from descope import AuthException
 
class DescopeAuthMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
 
    def __call__(self, request):
        session_token = request.headers.get('Authorization')
        if session_token:
            try:
                jwt_response = descope_client.validate_session(session_token=session_token)
                request.user = jwt_response  # Store user info in request
            except AuthException:
                return HttpResponseForbidden()
        
        response = self.get_response(request)
        return response

It's important to validate the aud claim in your session token to ensure the token was issued for your specific application. This prevents token reuse across different applications. You can use JWT Templates to customize the aud claim.

Here's how to validate the session token with an aud claim:

middleware.py
from django.http import HttpResponseForbidden
from descope import AuthException
 
class DescopeAuthMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
 
    def __call__(self, request):
        session_token = request.headers.get('Authorization')
        if session_token:
            try:
                jwt_response = descope_client.validate_session(
                    session_token=session_token,
                    audience="__ProjectID__"
                )
                request.user = jwt_response  # Store user info in request
            except AuthException:
                return HttpResponseForbidden()
        
        response = self.get_response(request)
        return response

Once you've implemented the basic session validation, you can enhance your application with these additional features:

Additional Resources

Have You Implemented the Frontend Yet?

When integrating Descope into your application, you have three options depending on how much control you want over your frontend authentication experience and session management:

OptionDescriptionBest For
Use Descope FlowsDesign your authentication screens and flows visually in the Descope Console with little or no frontend code. We handle all session management for you.Fastest setup with minimal custom frontend work.
Use Descope Client SDKsBuild your own login screens and authentication experiences in your frontend using code, while relying on Descope's SDKs to manage sessions (login, logout, refresh).Customizable UX with simplified session handling.
Use Descope Backend SDKsBuild your own frontend and your own backend APIs for authentication. You fully manage sessions, tokens, and authentication logic yourself.Maximum flexibility and control, at the cost of more engineering effort.
Was this helpful?

On this page