API key permissions for the Django REST Framework
Project description
Django REST Framework API Key
API key permissions for the Django REST Framework.
Introduction
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.
Features
- ✌️ Simple to use: create, view and revoke API keys via the admin site, or use built-in helpers to create API keys programmatically.
- 🔒 As secure as possible: API keys are treated with the same level of care as user passwords. They are only visible at creation and hashed before storing in the database.
- 🎨 Customizable: satisfy specific business requirements by building your own customized API key models, permission classes and admin panels.
Should I use API keys?
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:
- Blocking anonymous traffic.
- Implementing API key-based throttling. (Note that Django REST Framework already has may built-in utilities for this use case.)
- Identifying usage patterns by logging request information along with the API key.
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.
Quickstart
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.
Changelog
See CHANGELOG.md.
Contributing
See CONTRIBUTING.md.
License
MIT
Changelog
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.
3.0.0 - 2023-09-30
Changed
- Use faster SHA512-based key hasher instead of password hashers. Reduces server load by making API key validation orders of magnitude faster (10x to 30x according to estimations, network latency aside). Hashed key will be transparently upgraded the first time
.is_valid()
is called. (Pull #244, Pull #251)
Removed
- Dropped support for Python 3.7, which has reached EOL. (Pull #247)
- Drop redundant
.has_object_permission()
implementation onBaseHasAPIKey
when using DRF 3.14.0 or above. (Pull #240)
Added
- Add official support for Python 3.11. (Pull #247)
2.3.0 - 2023-01-19
Removed
- Drop support for Python 3.6, which has reached EOL. (Pull #210)
Fixed
- Fix migration 0004 when run against a non default database. (Pull #215)
2.2.0 - 2022-03-11
Added
- Added support for Django config detection for different versions (PR #187)
Changed
- Add official support for Django 3.2 and Python 3.9 and 3.10 (PR #189)
- Bumped
hashed_key
field'smax_length
from 100 to 150 to address length issue withargon2-cffi
(PR #193)
2.1.0 - 2021-09-24
Added
- Add support for custom API
keyword
. (Pull #175)
2.0.0 - 2020-04-07
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.
Removed
- Dropped support for Django 2.0 and Django 2.1. (Pull #126)
- Dropped support for Python 3.5. (Pull #84)
Added
- Add support for Django 3.0. (Pull #82)
- Add support for Python 3.8. (Pull #81)
- Add
BaseAPIKeyManager.get_from_key()
to allow retrieving API keys from views. (Pull #93) - Add type annotations, and partial support for
django-stubs
anddjangorestframework-stubs
. (Pull #88, Pull #122)
1.4.1 - 2019-08-24
Added
- Now ships with type annotations (PEP 561). (Pull #73)
1.4.0 - 2019-07-16
NOTE: this release contains migrations. See Upgrade to v1.4 for detailed instructions.
Added
- The
prefix
andhashed_key
are now stored in dedicated fields on theAPIKey
model. (Pull #62)
1.3.0 - 2019-06-28
NOTE: this release contains migrations. In your Django project, run them using:
python manage.py migrate rest_framework_api_key
Added
- Add abstract API key model (
AbstractAPIKey
) and base manager (BaseAPIKeyManager
). (Pull #36) - Add base permissions (
BaseHasAPIKey
). (Pull #46)
Changed
- The
id
field ofAPIKey
is now non-editable
. APIKeyModelAdmin
does not definefieldsets
anymore. This allows subclasses to benefit from Django's automatic fieldsets. (Pull #52)
Fixed
- Explicitly use
utf-8
encoding insetup.py
, which could previously lead to issues when installing on certain systems. (Pull #58)
1.2.1 - 2019-06-03
Fixed
- Fixed a critical bug in
APIKeyModelAdmin
that preventedrest_framework_api_key
from passing Django system checks. (Pull #39)
1.2.0 - 2019-05-29
NOTE: this release contains migrations. In your Django project, run them using:
python manage.py migrate rest_framework_api_key
Added
- API keys can now have an optional
expiry_date
. (Pull #33)HasAPIKey
denies access if the API key has expired, i.e. ifexpiry_date
, if set, is in the past. - It is now possible to search by
prefix
in the API key admin panel. - The
prefix
is now displayed in the edit view of the API key admin panel.
1.1.0 - 2019-05-14
Added
- Improve documentation on which password hasher is used.
- Add tests against the Argon2, BcryptSHA256 and PBKDF2SHA1 hashers. (Pull #32)
Fixed
- Fix support for password hashers that generate hashes that contain dots. (Pull #31)
1.0.0 - 2019-04-24
This release is incompatible with 0.x. See Upgrade to 1.0 for migration steps.
Removed
- Remove
HasAPIKeyOrIsAuthenticated
permission class. You should use bitwise composition now, e.g.HasAPIKey | IsAuthenticated
. - Drop the
DRF_API_KEY_*
settings. (Pull #19)
Changed
- Switch to a new API key generation and validation scheme. Clients must now authorize using a single API key header (Pull #19). The header is
Authorization
by default. It can be customized using theAPI_KEY_CUSTOM_HEADER
setting (Pull #26). Use thename
field to identify clients.
Added
- Add support for Django 2.2. (Pull #27)
- Add programmatic API key creation using
APIKey.objects.create_key()
. (Pull #19)
Fixed
- Improved API key storage using Django's password hashing helpers. (Uses the default Django password hasher.) (Pull #19)
0.4.0 - 2019-04-21
Removed
- Drop support for Python 3.4. Only 3.5, 3.6 and 3.7 are supported now.
- Drop support for Django < 2.0. Only 2.0 and 2.1 are supported now.
Fixed
HasAPIKey
now implements.has_object_permissions()
, which allows to compose it with other permission classes and perform object-level permission checks. (Pull #25)
0.3.1 - 2018-11-17
Initial changelog entry.
Added
APIKey
model.HasAPIKey
andHasAPIKeyOrIsAuthenticated
permission classes.- Generate, view and revoke API keys from the Django admin.
- Authenticate requests using the
Api-Token
andApi-Secret-Key
headers. Customizable via theDRF_API_KEY_TOKEN_HEADER
andDRF_API_KEY_SECRET_KEY_HEADER
settings.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file djangorestframework-api-key-3.0.0.tar.gz
.
File metadata
- Download URL: djangorestframework-api-key-3.0.0.tar.gz
- Upload date:
- Size: 36.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.10.13
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | f18cdfa45aaea10fd4daaebffa60481ce4002c9b9ef6c551ef1fc21dadf28845 |
|
MD5 | 477ac4b9269190e3279c4a084518c65d |
|
BLAKE2b-256 | 784af30dc4121839323acfaee8d9938c0ff0630945f9d1765643adf420c1f042 |
File details
Details for the file djangorestframework_api_key-3.0.0-py3-none-any.whl
.
File metadata
- Download URL: djangorestframework_api_key-3.0.0-py3-none-any.whl
- Upload date:
- Size: 15.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.10.13
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | b9443cd864e43caebdd330224f9309957b38128267fbc9dc1ba2f3fa1c8414d0 |
|
MD5 | d574068d1bc5039fe97187f2e5c685bd |
|
BLAKE2b-256 | 188b5b7cf37dfc3474f06eda417ea0dce4c970e3bde85f72e71d31225a46c7c4 |