djangorestframework-api-key

Warnings

• breaking Version 3.0.0 introduced a significant change by switching from password hashers to a faster SHA512-based key hasher. While existing keys are transparently upgraded upon the first `is_valid()` call, this is a major internal change that improves performance. Python 3.7 support was also dropped.
  Fix: No direct code change is required for existing keys, as the upgrade is automatic. Ensure your environment supports Python >=3.8. Review performance implications and test thoroughly after upgrading.
• breaking Version 2.3.0 dropped support for Python 3.6.
  Fix: Ensure your project runs on Python 3.7 or newer. Python 3.8+ is recommended for recent versions.
• gotcha The `hashed_key` field's `max_length` was increased from 100 to 150 in version 2.2.0 to accommodate longer hashes, particularly when using `argon2-cffi`. If you have custom API key models based on `AbstractAPIKey` and are upgrading from an older version, you may need to manually adjust your migration files or database schema to reflect this change if you encounter issues or plan to use stronger hashing algorithms.
  Fix: For custom models, verify your `hashed_key` field's `max_length`. If necessary, create a data migration to alter the field or adjust your custom model's definition to `max_length=150`.
• gotcha It is highly recommended to pin your dependency to the latest major version (e.g., `djangorestframework-api-key==3.*`) due to potential breaking changes between major releases.
  Fix: Always specify the major version in your `requirements.txt` or `pyproject.toml` (e.g., `djangorestframework-api-key~=3.1`).
• gotcha This package is designed for *authorization* (e.g., controlling access for server-to-server communication, blocking anonymous traffic, or implementing API key-based throttling) and is *not* intended for user *authentication* (identifying individual human users). For user authentication, consider Django REST Framework's built-in authentication or OAuth solutions.
  Fix: Understand the use case for API keys: they are best for machine-to-machine interactions or public API access control. Do not use them to identify or log in individual users.
• gotcha When an API key is created (either via the Django admin or programmatically with `APIKey.objects.create_key()`), the full, unhashed key is shown only once. After this initial display, it cannot be retrieved. If a key is lost, it must be regenerated.
  Fix: Always securely store the generated API key immediately after creation and provide it to the client. Do not rely on being able to retrieve it later from the database.

Install

• pip install djangorestframework-api-key Install stable version

Imports

• HasAPIKey

  from rest_framework_api_key.permissions import HasAPIKey

• APIKey

  from rest_framework_api_key.models import APIKey

  For programmatic API key creation and management.

Quickstart

To get started, add `rest_framework_api_key` to your `INSTALLED_APPS` in `settings.py` and run migrations. Then, configure `HasAPIKey` as a default permission class in `REST_FRAMEWORK` settings or apply it to individual views. Clients will then need to provide the generated API key in the `Authorization: Api-Key <API_KEY>` header. API keys can be created via the Django admin panel or programmatically using `APIKey.objects.create_key()`. The full key is only visible upon creation; subsequently, only its prefix is shown for security.

import os

# settings.py
INSTALLED_APPS = [
    # ...
    'rest_framework',
    'rest_framework_api_key',
]

REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework_api_key.permissions.HasAPIKey'
    ]
}

# --- Example usage in a Django REST Framework view ---

# In your_app/views.py
from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework_api_key.permissions import HasAPIKey
from rest_framework_api_key.models import APIKey

class ProtectedView(APIView):
    permission_classes = [HasAPIKey]

    def get(self, request, format=None):
        # You can access the APIKey object associated with the request
        api_key = request.user # In this library, `request.user` is the APIKey instance
        return Response({
            "message": f"Hello, API Key client! Key name: {api_key.name}"
        })

# To create an API key programmatically (e.g., in a management command or shell):
# from rest_framework_api_key.models import APIKey
# api_key_obj, key = APIKey.objects.create_key(name="My Service Key")
# print(f"New API Key: {key}") # This is the ONLY time the full key is shown!
# Ensure you store this 'key' value securely and provide it to your client.

# Example of how a client would use this key:
# Authorization: Api-Key <THE_GENERATED_KEY>