API key permissions for the Django REST Framework
API key permissions for the Django REST Framework.
Django REST Framework API Key is a library for allowing server-side clients to safely use your API. These clients are typically third-party backends and services (i.e. machines) which do not have a user account but still need to interact with your API in a secure way.
There are important security aspects you need to consider before switching to an API key access control scheme. We've listed some of these in Security caveats, including serving your API over HTTPS.
Besides, see Why and when to use API keys for hints on whether API keys can fit your use case.
API keys are ideal in the following situations:
They can also present enough security for authorizing internal services, such as your API server and an internal frontend application.
Please note that this package is NOT meant for authentication. You should NOT use this package to identify individual users, either directly or indirectly.
If you need server-to-server authentication, you may want to consider OAuth instead. Libraries such as django-oauth-toolkit can help.
Install with pip
:
pip install "djangorestframework-api-key==3.*"
Note: It is highly recommended to pin your dependency to the latest major version (as depicted above), as breaking changes may and will happen between major releases.
Add the app to your INSTALLED_APPS
:
# settings.py
INSTALLED_APPS = [
# ...
"rest_framework",
"rest_framework_api_key",
]
Run the included migrations:
python manage.py migrate
To learn how to configure permissions and manage API keys, head to the Documentation.
See CHANGELOG.md.
See CONTRIBUTING.md.
MIT
All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog. This project adheres to Semantic Versioning.
.is_valid()
is called. (Pull #244, Pull #251).has_object_permission()
implementation on BaseHasAPIKey
when using DRF 3.14.0 or above. (Pull #240)hashed_key
field's max_length
from 100 to 150 to address length issue with argon2-cffi
(PR #193)keyword
. (Pull #175)NOTE: this release drops compatibility with certain Python and Django versions, but contains no other breaking changes. See Upgrade to 2.0 for detailed migration steps.
BaseAPIKeyManager.get_from_key()
to allow retrieving API keys from views. (Pull #93)django-stubs
and djangorestframework-stubs
. (Pull #88, Pull #122)NOTE: this release contains migrations. See Upgrade to v1.4 for detailed instructions.
prefix
and hashed_key
are now stored in dedicated fields on the APIKey
model. (Pull #62)NOTE: this release contains migrations. In your Django project, run them using:
python manage.py migrate rest_framework_api_key
AbstractAPIKey
) and base manager (BaseAPIKeyManager
). (Pull #36)BaseHasAPIKey
). (Pull #46)id
field of APIKey
is now non-editable
.APIKeyModelAdmin
does not define fieldsets
anymore. This allows subclasses to benefit from Django's automatic fieldsets. (Pull #52)utf-8
encoding in setup.py
, which could previously lead to issues when installing on certain systems. (Pull #58)APIKeyModelAdmin
that prevented rest_framework_api_key
from passing Django system checks. (Pull #39)NOTE: this release contains migrations. In your Django project, run them using:
python manage.py migrate rest_framework_api_key
expiry_date
. (Pull #33) HasAPIKey
denies access if the API key has expired, i.e. if expiry_date
, if set, is in the past.prefix
in the API key admin panel.prefix
is now displayed in the edit view of the API key admin panel.This release is incompatible with 0.x. See Upgrade to 1.0 for migration steps.
HasAPIKeyOrIsAuthenticated
permission class. You should use bitwise composition now, e.g. HasAPIKey | IsAuthenticated
.DRF_API_KEY_*
settings. (Pull #19)Authorization
by default. It can be customized using the API_KEY_CUSTOM_HEADER
setting (Pull #26). Use the name
field to identify clients.APIKey.objects.create_key()
. (Pull #19)HasAPIKey
now implements .has_object_permissions()
, which allows to compose it with other permission classes and perform object-level permission checks. (Pull #25)Initial changelog entry.
APIKey
model.HasAPIKey
and HasAPIKeyOrIsAuthenticated
permission classes.Api-Token
and Api-Secret-Key
headers. Customizable via the DRF_API_KEY_TOKEN_HEADER
and DRF_API_KEY_SECRET_KEY_HEADER
settings.