README

django-apikey
=============

Simple, straight forward API key authentication for django-piston.

Requirements (can be install with pip install -r requirements.txt):
django-piston
Using django.contrib.auth

You can install into a virtualenv and run the tests:
./manage.py test key --settings="key.settings"

There is a simple template file in templates/keys.html.  This file is used
by all the project's views.


To use django-apikey with django-piston:

from key.auth import ApiKeyAuthentication
auth = ApiKeyAuthentication( )
bucket_handler = Resource( handler=MyHandler, authentication=auth )


By default, clients use the X-Api-Authorization header to pass the API key:

headers['X-Api-Authorization'] = 'your.api.key.here'

This can be modified in the settings.py of your Django project by using the APIKEY_AUTHORIZATION_HEADER setting, e.g.:

APIKEY_AUTHORIZATION_HEADER = 'X-MyCoolApp-Authorization'

This setting defaults to the X-Api-Authorization header.

The numer of keys that a User can be defined in your project's settings.py. \  
Setting APIKEY_MAX_KEYS to a positive integer will create a limit on the number of keys an individual User can create.  Setting it to -1 allows Users to create an
unlimited number of keys.

APIKEY_MAX_KEYS = -1

For example, this will allow a User to make an unlimited number of keys.

You can control the length of the key by setting APIKEY_KEY_SIZE.  Currently, there is a maximum
key size of 32 characters.

The following signals are generated / used by this package:

api_user_created : generated when a ApiKeyProfile is attached to a User
api_key_created : generated when a ApiKey is created
api_user_logged_in : generated when a user connects to REST service with key authentication
api_user_logged_out : generated when a user explicitly logs out of the REST service


You must create ApiKeyProfiles right from your code (as you may want restrict some users from having access to your API), to do that, you can just add the following code into some of your models.py files:

from django.contrib.auth.models import User
from django.db.models.signals import post_save
from key.models.actions import create_key_profile_signal

post_save.connect(create_key_profile_signal, sender=User)

Whenever you create a new user, it will create a new ApiKeyProfile.