Add fine-grained authorization to a Django app

Build a Django app for a blogging platform that registers users in Permit.io and allows only users with the Author role to create posts. This tutorial is for Python backend developers who want to enforce Permit.io policies from Django views.

When you finish, your Django app has two endpoints:

Endpoint	What it does
POST /register	Syncs a user to Permit.io and assigns the user the Reader role in the default tenant
POST /posts	Calls permit.check() and returns 403 unless the user has permission to create a Post

Prerequisites

• A Permit.io account. See Create a Permit.io account.
• Python 3 with Django 5.0 or later installed, and a Django project named permit_demo. To create the project, run django-admin startproject permit_demo.
• Node.js and npm, to install the Permit CLI.
• Docker, to run the policy decision point (PDP) container.

1. Configure the policy in Permit

Create the blogging platform policy with the Permit CLI. If your environment already has a policy with a Post resource and an Author role that can create posts, skip to 2. Get your API key.

1

Install the Permit CLI

The Permit CLI creates policies and runs the PDP from your terminal. Install the CLI with npm:

npm install -g @permitio/cli

Run permit to confirm that the CLI is installed.

2

Sign in with the Permit CLI

Authenticate the CLI with your Permit.io account:

permit login

The command opens a browser window where you sign in. After you sign in, the CLI uses your default environment. To use a different environment, run permit env select and choose the environment.

3

Apply the blogging platform template

Permit CLI templates create a policy with predefined resources, roles, and rules. To see the available templates, run permit env template list. The template source files are in the Permit CLI repository.

Apply the blogging-platform template to your environment:

permit env template apply --template blogging-platform

The CLI prints a success message when the template is applied.

4

Review the policy in the Policy Editor

In the Permit dashboard, select your project and open the Policy screen.

The blogging-platform template creates:

Policy element	What the template defines
Resources	Post (with a premium boolean attribute) and Comment, each with create, read, update, and delete actions
Roles	Admin (all actions), Author (create and read posts, read comments), Reader (create and read comments), and Premium Reader (read posts and comments)
Relationship	A Post is the parent of its Comment instances. An Author of a post instance becomes a Moderator of the comments on that post. This rule is relationship-based access control (ReBAC).
Resource set	Free Post contains posts where premium is false. Readers can read free posts. This rule is attribute-based access control (ABAC).

This tutorial uses one rule from the policy: the Author role can create a Post, and the Reader role cannot. To change which role can perform an action, check or clear the box in the Policy Editor.

2. Get your API key

Your Django app and the PDP authenticate with Permit.io with your environment API key. Copy the API key of the environment where you applied the template. See Get your API key.

Keep the API key out of your code

Anyone with the environment API key can change that environment's policy through the Permit API. Load the key from an environment variable, and don't commit it.

3. Run the PDP

The PDP evaluates each permit.check() call against your policy. Start a PDP container with the Permit CLI:

permit pdp run

The command starts the PDP in Docker and prints the container ID and name. The PDP listens on port 7766, so your app connects to it at http://localhost:7766.

The Free Post resource set is an ABAC rule, and the Cloud PDP doesn't evaluate ABAC rules, so run the container PDP for this policy. To run the container with docker run instead, or to check that the PDP is healthy, see Run the PDP.

4. Build the Django app

The code in this section goes in the permit_demo package, the directory that contains settings.py.

1

Install the Python SDK

In your Django project, install the Permit Python SDK:

pip install permit

The permit package installs Pydantic with email validation, which the request models in this tutorial use. The views in this tutorial are async functions, so they use the asyncio version of the SDK. For all SDK options, see Check permissions with the Python SDK (asyncio).

2

Configure settings.py and urls.py

In permit_demo/settings.py, set the following values:

# permit_demo/settings.py
# Keep the INSTALLED_APPS, MIDDLEWARE, and ROOT_URLCONF values that startproject generated.

# Allow all hosts for demo
ALLOWED_HOSTS = ['*']

ALLOWED_HOSTS = ['*'] accepts requests for any host name, which is acceptable only for local testing. Leave the rest of the generated settings as they are: ROOT_URLCONF already points Django at permit_demo.urls, and the generated MIDDLEWARE list depends on the generated INSTALLED_APPS. If you drop django.contrib.sessions.middleware.SessionMiddleware from MIDDLEWARE, AuthenticationMiddleware raises ImproperlyConfigured on the first request.

In permit_demo/urls.py, map URLs to views:

# permit_demo/urls.py
from django.urls import path
from . import views

urlpatterns = [
    path("", views.root),
    path("register", views.register),
]

The urlpatterns list maps / to the root view and /register to the registration view in views.py.

3

Initialize the Permit client in views.py

Create a file named views.py in the permit_demo package with the following code:

# permit_demo/views.py
import os
import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from permit import Permit
from pydantic import BaseModel, EmailStr, ValidationError

permit = Permit(
    token=os.getenv("PERMIT_API_KEY"),
    pdp=os.getenv("PDP_URL", ""),
)

class UserIn(BaseModel):
    email: EmailStr
    first_name: str
    last_name: str

The UserIn Pydantic model validates the body of registration requests. The Permit client reads two environment variables:

Variable	Value
PERMIT_API_KEY	Your environment API key from 2. Get your API key
PDP_URL	The PDP address from 3. Run the PDP: http://localhost:7766

4

Add the register view

Add the following code to views.py. The register view syncs the user to Permit.io with permit.api.users.sync(), then assigns the user the Reader role in the default tenant with permit.api.users.assign_role().

# Root endpoint
async def root(request):
    return JsonResponse({"message": "Hello, Permit-Django!"})

# Register a new user
@csrf_exempt
async def register(request):
    try:
        data = json.loads(request.body)
        user = UserIn(**data)
    except ValidationError as e:
        return JsonResponse(e.errors(), status=422, safe=False)

    # Sync user with Permit
    synced = await permit.api.users.sync({
        "key": user.email,
        "email": user.email,
        "first_name": user.first_name,
        "last_name": user.last_name,
    })

    # Assign role as part of registration
    role_assignment = await permit.api.users.assign_role({
        "user": user.email,
        "role": "Reader",
        "tenant": "default",
    })

    # Continue with your app's registration logic

    return JsonResponse({
        "message": "User registered and role assigned",
        "user": synced.dict() if hasattr(synced, "dict") else vars(synced),
        "role_assignment": role_assignment.dict() if hasattr(role_assignment, "dict") else vars(role_assignment),
    }, status=201)

The user's email address is the user key in Permit.io. Your app passes the same key to permit.check(). The root view returns a greeting that confirms the app is running.

5

Protect the posts view with permit.check()

Add the following code to views.py. The posts view asks the PDP whether the user in the request body can create a Post, and returns 403 when the PDP denies the request.

# permit_demo/views.py
class PermissionCheck(BaseModel):
    user: str

# Check access to the resource
@csrf_exempt
async def posts(request):
    action = 'create'
    resource = 'Post'
    try:
        data = json.loads(request.body)
        check = PermissionCheck(**data)
    except ValidationError as e:
        return JsonResponse(e.errors(), status=422, safe=False)
    except Exception as e:
        print("Error in posts:", str(e))
        return JsonResponse({"error": str(e)}, status=500)

    try:
        permitted = await permit.check(check.user, action, resource)
    except Exception as e:
        print("Error during permission check:", str(e))
        return JsonResponse({"error": "Permission check failed"}, status=500)

    if permitted:
        return JsonResponse({"message": "User is permitted"})
    else:
        return JsonResponse({"message": "User is not permitted"}, status=403)

permit.check() takes the user key, the action, and the resource type, and returns True or False. To protect other endpoints, such as commenting or editing, change the action and resource values.

Add a posts path to the existing urlpatterns list in permit_demo/urls.py, next to the root and register paths:

# permit_demo/urls.py
urlpatterns = [
    path("", views.root),
    path("register", views.register),
    path("posts", views.posts),
]

note

In a production app, take the user key from your authenticated session. This example reads the user key from the request body so that you can test the endpoint with curl.

6

Start the Django app

From the directory that contains manage.py, set the environment variables and start the development server, replacing <YOUR_API_KEY> with your API key:

export PERMIT_API_KEY=<YOUR_API_KEY>
export PDP_URL=http://localhost:7766
python manage.py runserver 8000

The app listens on http://localhost:8000.

5. Test the permission check

Register two users, give one of them the Author role, and confirm that the PDP allows only that user to create a post.

1

Register two users

In a second terminal, register John and Emma:

curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{"email": "john@example.com", "first_name": "John", "last_name": "Doe"}'

curl -X POST http://localhost:8000/register \
  -H "Content-Type: application/json" \
  -d '{"email": "emma@example.com", "first_name": "Emma", "last_name": "Den"}'

Each request returns "message": "User registered and role assigned", the synced user under user, and the role assignment under role_assignment, with "role": "Reader" and "tenant": "default". Both users appear in the Directory screen of the Permit dashboard.

2

Assign John the Author role

Both users have the Reader role, which can't create posts. Give John the Author role in the Permit dashboard:

1. Open the Directory screen and select john@example.com to open the Edit User panel.
2. Under Permissions Per Tenant, select the Default Tenant.
3. In Top Level Access, add the Author role.
4. Click Save.

For other ways to assign roles, including the API and SDK, see Sync users.

3

Check that John can create a post and Emma can't

Send a POST /posts request for John:

curl -X POST http://localhost:8000/posts \
  -H "Content-Type: application/json" \
  -d '{"user": "john@example.com"}'

The PDP allows the request because John has the Author role. The app returns HTTP 200 with "message": "User is permitted" in the JSON body.

Send the same request for Emma:

curl -X POST http://localhost:8000/posts \
  -H "Content-Type: application/json" \
  -d '{"user": "emma@example.com"}'

The PDP denies the request because Emma has only the Reader role. The app returns HTTP 403 with "message": "User is not permitted" in the JSON body.

Each check also appears in the Audit Log screen of the Permit dashboard, with the user, action, resource, and decision.

Next steps

• Check permissions with the Python SDK (asyncio): SDK installation, configuration, and more permit.check() examples.
• Check permissions with permit.check(): check against tenants, resource instances, and attributes.
• Build RBAC policies: create roles and permissions for your own resources.
• Use your authentication provider with Permit: take the user key from your sign-in flow instead of the request body.

Next step

Going to production? Review the PDP deployment checklist, or talk to an engineer about scale and latency.