django-locksmith 0.7.1

Settings

To use locksmith.hub it is necessary to add a few things to settings.py:

In INSTALLED_APPS add ‘locksmith.hub’.

In AUTHENTICATION_BACKENDS add ‘locksmith.hub.auth_backend.LocksmithBackend’

This will make the locksmith.hub models and management command available and allow users to sign in using their email and apikey.

Optional settings:

LOCKSMITH_EMAIL_SUBJECT: if set will be used as the subject of the email sent when users request a key. (defaults to ‘API Registration’) LOCKSMITH_REPLICATED_APIS: Locksmith has two key synchronization mechanisms. The older, stateful mechanism is used by default. To opt into using the newer, stateless mechanism for an API, add the name of the API here. This is a temporary setting. In 0.8 all APIs will use the new mechanism and this setting will prompt a deprecation warning.

Templates

The locksmith.hub app provides a set of front-end templates that can be integrated into your website. To provide for maximum flexibility, these templates extend your project base template. You should specify the path to that base template using LOCKSMITH_BASE_TEMPLATE.

Each of the locksmith.hub views allow you to specify a view to render instead of the default. This allows you to use {% include %} tags in both the base and top-level template. If you need to functionality you can override each view’s template using these settings:

LOCKSMITH_ANALYTICS_INDEX_TEMPLATE LOCKSMITH_API_ANALYTICS_TEMPLATE LOCKSMITH_KEY_ANALYTICS_TEMPLATE LOCKSMITH_KEYS_LIST_TEMPLATE LOCKSMITH_KEYS_LEADERBOARD_TEMPLATE LOCKSMITH_REGISTER_TEMPLATE

URLs

locksmith.hub provides two sets of URL patterns, one for registration and the other for analytics.

They can be added to your urls.py with the following line:

(r’^’, include(‘locksmith.hub.urls’)),

This adds an accounts/ path that contains user-facing urls and an analytics/ path that adds analytics views that are only accessible by staff members.

Installation

• add ‘locksmith.(mongo)auth’ to INSTALLED_APPS

• add a line like: (r’^api/’, include(‘locksmith.(mongo)auth.urls’)) to urls.py

Add the following settings to your settings.py:

LOCKSMITH_HUB_URL

URL to your locksmith.hub instance

LOCKSMITH_SIGNING_KEY

signing key for this locksmith instance

LOCKSMITH_API_NAME

name of this locksmith instance

You can optionally enable the APIKeyMiddleware by adding 'locksmith.(mongo)auth.middleware.APIKeyMiddleware' to your MIDDLEWARE_CLASSES. This middleware makes use of two more optional settings:

LOCKSMITH_QS_PARAM

Query String parameter to check for API key (default: apikey)

LOCKSMITH_HTTP_HEADER

HTTP header to check for API key (default: HTTP_X_APIKEY)

Usage

If using locksmith.auth the locksmith.auth.models.ApiKey model is used to store information on the API key.

If using locksmith.mongoauth a collection named locksmith.keys will be created with ‘_id’, ‘status’, and ‘email’ fields.

When a user passes a key to your API you should check if such an ApiKey object exists and if it is active (ie. status=’A’) before serving the request. This check is handled automatically if you are using the provided APIKeyMiddleware.

Reporting Statistics

To report usage of your API back to the locksmith.hub instance you can call ./manage.py apireport daily.

connecting a locksmith.hub and locksmith.auth instance

Assuming that you have a locksmith.hub instance and a locksmith.(mongo)auth instance running as indicated above, the final step is to connect the two so that API signups become actual usable keys and analytics get back.

# hub: Add a new locksmith.hub.Api instance for the new API (choosing a name and signing key) # hub: Push all existing keys to the new API’s locksmith auth endpoints by calling ./manage.py pushkeys

Assuming you already have a regular cronjob that pushes out new keys the new API will now get notified of new keys along with all of your other APIs.

TODO: document how non-locksmith.auth-enabled APIs can push to locksmith.hub