Settings

Some of Django REST Framework Simple API Key's behavior can be customized through settings variables in settings.py. You can find below the default DRF_API_KEY setting.

# Django project settings.py
...

DRF_API_KEY = {
     "FERNET_SECRET": "",
     "API_KEY_LIFETIME": 365,
     "AUTHENTICATION_KEYWORD_HEADER": "Api-Key",
     "ROTATION_PERIOD": timedelta(days=7),
     "ROTATION_FERNET_SECRET": "",
     "IGNORED_ROUTES": ["/admin/"]  # Routes that should be ignored by API key authentication
}

Above, the default values for these settings are shown.

FERNET_SECRET

The fernet key (Fernet) is used to encrypt and decrypt API Keys.

To generate a fresh fernet key, you can use the following command:

python manage.py generate_fernet_key

Make sure to store it somewhere safe and treat it as you will treat the SECRET_KEY Django setting.

API_KEY_LIFETIME

Determines the validity period of a generated Api Key. The default value is 365 days.

AUTHENTICATION_KEYWORD_HEADER

Determines the keyword that should come with every request made to your API. The default value is Api-Key and it is used in the following format:

Api-Key API_KEY

ROTATION_PERIOD

The duration for which key rotation remains active. After this period, the rotation process completes and you'll need to manually swap the FERNET_SECRET and ROTATION_FERNET_SECRET values.

Default: timedelta(days=7)

Example:

from datetime import timedelta

DRF_API_KEY = {
    "ROTATION_PERIOD": timedelta(days=7),  # Rotation active for 7 days
}

ROTATION_FERNET_SECRET

The ROTATION_FERNET_SECRET is a secondary Fernet key (Fernet) utilized within the MultiFernet cryptographic scheme. While the primary Fernet key (fernet_key) is used for the main encryption and decryption, the ROTATION_FERNET_SECRET plays a pivotal role during key rotation phases.

In the context of MultiFernet:

• New tokens are encrypted using the ROTATION_FERNET_SECRET.
• Tokens can be decrypted with either the ROTATION_FERNET_SECRET enabling a smooth key rotation without rendering existing tokens obsolete.

python manage.py generate_fernet_key

This strategic usage ensures that as you transition to a new key, older tokens encrypted with the previous key remain valid, and new tokens are encrypted using the new key. Thus, a seamless transition is achieved, enhancing security without causing disruptions.

IGNORED_ROUTES

A list of URL paths that should be ignored by the API Key Analytics Middleware. Any request to a path that starts with any of these routes will not be tracked in the analytics. The default value is ["/admin/"]. This setting is specifically used by the analytics middleware to determine which routes should be excluded from usage tracking.

Example:

DRF_API_KEY = {
    "IGNORED_ROUTES": [
        "/admin/",  # Excludes admin panel routes from analytics
        "/api/documents/",  # Excludes document API routes from analytics
        "/health/",  # Excludes health check endpoints from analytics
    ]
}

ENFORCE_HTTPS

By default, we enforce HTTPS connections in production to prevent API keys from being transmitted over unencrypted HTTP. If someone tries to use an API key over HTTP, the request will be rejected.

Default: None (auto-detects: True when DEBUG=False, False when DEBUG=True)

Example:

DRF_API_KEY = {
    "ENFORCE_HTTPS": True,  # Reject HTTP requests in production
}

Note: ⚠️ Always set this to True in production! Sending API keys over HTTP is like sending passwords in plain text. See Security for more details.

ENABLE_AUDIT_LOGGING

Controls whether security events are logged. When enabled, the package logs authentication attempts, API key creation/revocation, and security-related events.

Default: True

Example:

DRF_API_KEY = {
    "ENABLE_AUDIT_LOGGING": True,  # Log security events
}

See Security for information about what events are logged and how to access them.

MAX_ENDPOINTS_PER_KEY

Limits the number of unique endpoints that can be tracked per API key in analytics. This helps prevent abuse and keeps your database size manageable.

Default: 1000

Example:

DRF_API_KEY = {
    "MAX_ENDPOINTS_PER_KEY": 1000,  # Limit tracked endpoints
}

MAX_ENDPOINT_LENGTH

Limits the maximum length of endpoint paths stored in analytics. This prevents malicious or malformed endpoint paths from causing issues.

Default: 500

Example:

DRF_API_KEY = {
    "MAX_ENDPOINT_LENGTH": 500,  # Maximum endpoint path length
}

IP_ADDRESS_HEADER

Specifies which HTTP header to use for extracting the client IP address. This is useful when your application is behind a proxy or load balancer.

Default: "REMOTE_ADDR"

Example:

DRF_API_KEY = {
    "IP_ADDRESS_HEADER": "HTTP_X_FORWARDED_FOR",  # Use X-Forwarded-For header
}

Note: The authentication backend safely handles proxy headers to prevent IP spoofing. See Security for more details.

API_KEY_CLASS

The fully qualified path to your custom API key model class, if you've created one. This is used by the analytics addon to reference the API key model.

Default: "drf_simple_apikey.Apikey"

Example:

DRF_API_KEY = {
    "API_KEY_CLASS": "myapp.models.CustomAPIKey",  # Use custom model
}

Note: Only change this if you've created a custom API key model. See Customizing API Key Model for details.