djangorestframework-api-key

🔐 API key permissions for the Django REST Framework.

Important: Make sure to pin your dependency to 0.x (i.e. rest_framework_api_key < 1.0). The upcoming 1.0 release will introduce a new (non-backwards compatible) API key scheme.

Features

djangorestframework-api-key allows server-side clients to safely use your API.

Server-side clients are third-party backends and services which does not have a user account but still need to interact with your API in a secure way.

Intended to be:

• ✌️ Simple to use: create, view and revoke API keys via the admin site.
• 🔒 As secure as possible: secret keys are treated with the same level of care than passwords. They are hashed before being stored in the database and only visible at creation.

Note: there are important security aspects you need to consider before switching to an API key access control scheme. See Security caveats.

Installation

• Install from PyPI:

$ pip install djangorestframework-api-key

• 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

Usage

Setting permissions

This package provides permission classes to allow external clients to use your API:

• HasAPIKey: this permission class requires all clients to provide a valid API key, regardless of whether they provide authentication details.
• HasAPIKeyOrIsAuthenticated: if you want to allow clients to provide either an API key or authentication credentials, use this permission class instead.

As with every permission class, you can either use them globally:

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework_api_key.permissions.HasAPIKey',
    ]
}

or on a per-view basis:

# views.py
from rest_framework.views import APIView
from rest_framework_api_key.permissions import HasAPIKey

class UserListView(APIView):
    permission_classes = [HasAPIKey]
    # ...

See Setting the permission policy (DRF docs) for more information on using permission classes.

Making authorized requests

Once API key permissions are enabled on your API, clients can pass their API key via the Api-Token and Api-Secret-Key headers (this is customizable, see Settings):

$ curl -H 'Api-Token: YOUR_API_TOKEN_HERE' -H 'Api-Secret-Key: YOUR_API_SECRET_KEY_HERE' http://localhost:8000/my-resource/

To know under which conditions the access is granted, please see Grant scheme.

Creating and managing API keys

Admin site

When it is installed, djangorestframework-api-key adds an "API Key Permissions" section to the Django admin site where you can create, view and revoke API keys.

Settings

Note: values of header settings should be set according to the behavior of HttpRequest.META. For example, HTTP_API_KEY maps to the Api-Key header.

DRF_API_KEY_TOKEN_HEADER:

• Name of the header which clients use to pass their API token.
• Default value: "HTTP_API_TOKEN".

DRF_API_KEY_SECRET_KEY_HEADER:

• Name of the header which clients use the pass their API secret key.
• Default value: "HTTP_API_SECRET_KEY".

Security

Generation scheme

An API key is made of two parts:

• The API token: a unique, generated, public string of characters.
• The API secret key: a unique, generated string of characters that the client must keep private.

For obvious security purposes, djangorestframework-api-key does not store the secret key at all on the server. The latter is shown only once to the client upon API key creation.

Grant scheme

Access is granted if and only if all of the following is true:

1. The API key headers are present and correctly formatted (see Making authorized requests).
2. An unrevoked API key corresponding to the API token exists in the database.
3. The hash computed from the token and secret key matches the one of the API key.

Caveats

API keys ≠ Security: depending on your situation, you should probably not rely on API keys only to authenticate/authorize your clients.

Using API keys shifts the responsability of Information Security on your clients. This induces risks, especially if detaining an API key gives access to confidential information or write operations. For example, an attacker could impersonate clients if their let their API key leak because of insufficient security measures.

As a best practice, you should apply the Principle of Least Privilege: allow only those who require resources to access those specific resources. In other words: if your non-user client only needs to access a specific endpoint, add API permissions on that endpoint only.

Act responsibly!

Example project

An example project shows usage in the context of a Django project.

Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

License

MIT