Install¶

Requirements¶

Install the package¶

pip install django-keysmith

pip install "django-keysmith[drf]"

Add to Django¶

1. Register the app

# settings.py
INSTALLED_APPS = [
    # ...
    "keysmith",
]

2. Add middleware

Place KeysmithAuthenticationMiddleware immediately after Django's AuthenticationMiddleware:

MIDDLEWARE = [
    # ...
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "keysmith.django.middleware.KeysmithAuthenticationMiddleware",
]

The middleware extracts tokens and attaches context to every request. It does not block unauthenticated traffic - views opt in via @keysmith_required or DRF permission classes.

3. Run migrations

python manage.py migrate

Keysmith creates two tables: keysmith_token and keysmith_token_audit_log.

Optional: DRF defaults¶

Skip this if you only use plain Django views.

REST_FRAMEWORK = {
    "DEFAULT_AUTHENTICATION_CLASSES": [
        "keysmith.drf.auth.KeysmithAuthentication",
    ],
    "DEFAULT_PERMISSION_CLASSES": [
        "keysmith.drf.permissions.RequireKeysmithToken",
    ],
}

Verify¶

python manage.py shell

from keysmith.services.tokens import create_token

token, raw = create_token(name="smoke-test")
print(token.prefix)
print(raw)

System checks¶

Keysmith registers Django system checks that run on manage.py check:

Next: Tutorial - create a token and make your first authenticated request.