django-rest-authemail
=====================
`django-rest-authemail` is a Django/Python application that provides a RESTful API interface for user signup and authentication. Email addresses are used for authentication, rather than usernames. Because the authentication user model is based on Django's `AbstractBaseUser` and is itself abstract, the model can be extended without the need for additional database tables. Token authentication allows the API to be accessed from a variety of front ends, including Django, React and AngularJS clients, and iOS and Android mobile apps.
Features
--------
- API endpoints for signup, signup email verification, login, logout, password reset, password reset verification, password change, email change, and user detail.
- Extensible abstract user model.
- Perform password confirmation and other client-side validation on the front end for a better user experience.
- Token authentication.
- User models in the admin interface include inlines for signup and password reset codes.
- An example project is included and contains example UI templates.
- Version `2.0.5` and beyond
- Supports and tested with Python 3.6, 3.7, and 3.8.
- Supports and tested with Django 2.2.8, 2.2.13, 3.0, 3.1, and 3.2.
- Supports and tested with Django REST Framework 3.11.2 and 3.12.4.
- Version `1.10.2`
- Supports and tested with Python 3.6 and 3.7.
- Supports and tested with Django 1.11.17, 2.0, and 2.1.1.
- Supports and tested with Django REST Framework 3.7.1 and 3.11.0.
Installation
------------
`django-rest-authemail` is available on the Python Package Index (PyPI) at https://pypi.python.org/pypi/django-rest-authemail.
Install `django-rest-authemail` using one of the following techniques.
- Use pip. Note that particular versions of Django and the Django REST Framework may be installed.
```
pip install django-rest-authemail
```
- Download the .tar.gz file from PyPI and install it yourself.
- Download the [source from Github](http://github.com/celiao/django-rest-authemai) and install it yourself.
If you install it yourself, also install [Django](https://www.djangoproject.com/), the [Django REST Framework](http://www.django-rest-framework.org), and [requests](http://www.python-requests.org/en/latest).
Usage
-----
Create a Django project, if you haven't already. For example,
```python
django-admin startproject mysite
```
In the `settings.py` file of your project, include `rest_framework` and `rest_framework.authtoken` in `INSTALLED_APPS`. Set the authentication scheme for the Django REST Framework to `TokenAuthentication`.
```python
mysite/settings.py
----
INSTALLED_APPS = [
...
'rest_framework',
'rest_framework.authtoken',
...
]
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework.authentication.TokenAuthentication',
)
}
```
Optionally, you may add an `AUTH_EMAIL_VERIFICATION` setting to specify whether to enable email verification for new users on account registration/signup. Setting this to `False` will automatically verify newly created users.
Create a Django application for your user data. For example,
```python
python manage.py startapp accounts
```
In the `models.py` file of your application, extend `EmailAbstractUser`, add custom fields, and assign `objects` to `EmailUserManager()`. For example,
```python
accounts/models.py
----
from django.db import models
from authemail.models import EmailUserManager, EmailAbstractUser
class MyUser(EmailAbstractUser):
# Custom fields
date_of_birth = models.DateField('Date of birth', null=True, blank=True)
# Required
objects = EmailUserManager()
```
In the `settings.py` file of your project, include `authemail` and your application in `INSTALLED_APPS`. Set `AUTH_USER_MODEL` to the class of your user model. For example,
```python
mysite/settings.py
----
INSTALLED_APPS = [
...
'rest_framework',
'rest_framework.authtoken',
'authemail',
'accounts',
...
]
AUTH_USER_MODEL = 'accounts.MyUser'
```
In the `admin.py` file of your project, extend `EmailUserAdmin` to add your custom fields. For example,
```python
mysite/admin.py
----
from django.contrib import admin
from django.contrib.auth import get_user_model
from authemail.admin import EmailUserAdmin
class MyUserAdmin(EmailUserAdmin):
fieldsets = (
(None, {'fields': ('email', 'password')}),
('Personal Info', {'fields': ('first_name', 'last_name')}),
('Permissions', {'fields': ('is_active', 'is_staff',
'is_superuser', 'is_verified',
'groups', 'user_permissions')}),
('Important dates', {'fields': ('last_login', 'date_joined')}),
('Custom info', {'fields': ('date_of_birth',)}),
)
admin.site.unregister(get_user_model())
admin.site.register(get_user_model(), MyUserAdmin)
```
Create the database tables with Django's `makemigrations`, `migrate`, and create a superuser with `createsuperuser`.
```python
python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser
```
Check your setup by starting a Web server on your local machine:
```python
python manage.py runserver
```
Direct your browser to the `Django` `/admin` and log in.
```python
127.0.0.1:8000/admin
```
You should see `Users`, `Tokens`, `Password reset codes`, `Signup codes`, and `Groups`. If you click on `Users`, you should see your superuser account.
Add the `authemail` API endpoints to your project's `urls.py` file. For example,
```python
mysite/urls.py
----
from django.contrib import admin
from django.urls import include, path
urlpatterns = [
path('admin/', admin.site.urls),
path('api/accounts/', include('authemail.urls')),
]
```
When users signup or reset their password, they will be sent an email with a link and verification code. Include email settings as environment variables or in your project's `settings.py` file. For example,
```python
mysite/settings.py
----
# Email settings
# https://docs.djangoproject.com/en/3.1/topics/email/
# https://docs.djangoproject.com/en/3.1/ref/settings/#email-host
import os
EMAIL_FROM = os.environ.get('AUTHEMAIL_DEFAULT_EMAIL_FROM') or '<YOUR DEFAULT_EMAIL_FROM HERE>'
EMAIL_BCC = os.environ.get('AUTHEMAIL_DEFAULT_EMAIL_BCC') or '<YOUR DEFAULT_EMAIL_BCC HERE>'
EMAIL_HOST = os.environ.get('AUTHEMAIL_EMAIL_HOST') or 'smtp.gmail.com'
EMAIL_PORT = os.environ.get('AUTHEMAIL_EMAIL_PORT') or 587
EMAIL_HOST_USER = os.environ.get('AUTHEMAIL_EMAIL_HOST_USER') or '<YOUR EMAIL_HOST_USER HERE>'
EMAIL_HOST_PASSWORD = os.environ.get('AUTHEMAIL_EMAIL_HOST_PASSWORD') or '<YOUR EMAIL_HOST_PASSWORD HERE>'
EMAIL_USE_TLS = True
EMAIL_USE_SSL = False
```
Try out `authemail` API calls by firing up `python` and using the `authemail` wrapper methods (`runserver` should still be executing). For example,
```python
python
>>> from authemail import wrapper
>>> account = wrapper.Authemail()
>>> first_name = 'Your first name'
>>> last_name = 'Your last name'
>>> email = 'your_email@gmail.com'
>>> password = 'Your password'
>>> response = account.signup(first_name=first_name, last_name=last_name,
... email=email, password=password)
```
In the `Django` `/admin`, you should see a new user (not verified) and a new signup code. You should receive an email at `your_email@gmail.com`. Use the code in the email to verify your email address using the wrapper (normally, the link in the email would point to the front end, which would issue the signup verify request to the API):
```python
>>> code = '7f31e7a515df266532df4e00e0cf1967a7de7d17'
>>> response = account.signup_verify(code=code)
```
In the `Django` `/admin`, the new user is now verified and the signup code is absent. The new user can now login and you can inspect the associated login token:
```python
>>> response = account.login(email=email, password=password)
>>> account.token
'a84d062c1b60a36e6740eb60c6f9da8d1f709322'
```
You will find the same token for the user in the `Token` table in the `Django` `/admin`. Find out more information about the user (insert your token):
```python
>>> token = 'a84d062c1b60a36e6740eb60c6f9da8d1f709322'
>>> response = account.users_me(token=token)
>>> response
{'id': 1, 'first_name': 'Your first name', 'last_name': 'Your last name', 'email': 'your_email@gmail.com'}
```
Use the authentication token to logout:
```python
>>> response = account.logout(token=token)
>>> response
{'success': 'User logged out.'}
```
Play with password reset and change!
Django REST Framework Browsable API
-----
If you are having trouble getting your code to execute, or are just curious, try out the Django REST Framework Browsable API. If you type an `authemail` API endpoint into your browser, the Browsable API should appear (`runserver` should still be executing). For example,
```python
127.0.0.1:8000/api/accounts/signup
```
Enter information in the HTML form fields of the Browsable API, e.g.:
Then click on `POST`. You will either receive an error message to help in your debugging, or, if your signup was successful:
Try out the other `authemail` API endpoints with the Django REST Framework Browsable API.
Front End Example Project
----
Make `authemail` API calls from front end code. To get started, follow the steps in the`example_project` `README.md`. Enhance the Django code in the `example_project` or extend the concepts to React, AngularJS, iOS, and Android front ends.
When calling endpoints from the front end that require authentication (`logout`, `password/change`, and `users/me`), include the authorization token key in the HTTP header. For example,
```python
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```
Here's an example using ``curl``,
```python
curl -X GET 'http://127.0.0.1:8000/api/accounts/logout/' \
-H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'
```
Wrapper
-------
A wrapper is available to access the Authemail API with Python code. First create an instance of the Authemail class, then call methods to access the API. There is a one-to-one mapping between the endpoints and instance methods. For example,
```python
mysite/views.py
----
from authemail import wrapper
account = wrapper.Authemail()
response = account.signup(first_name=first_name, last_name=last_name,
email=email, password=password)
if 'detail' in response:
# Handle error condition
else:
# Handle good response
```
See `example_project/views.py` for more sample usage.
Authemail API Endpoints
-----------------------
For the endpoints that follow, the base path is shown as `/api/accounts`. This path is for example purposes. It can be customized in your project's `urls.py` file.
**POST /api/accounts/signup**
Call this endpoint to sign up a new user and send a verification email. Sample email templates are found in `authemail/templates/authemail`. To override the email templates, copy and modify the sample templates, or create your own, in `your_app/templates/authemail`.
Your front end should handle password confirmation, and if desired, require the visitor to input their first and last names.
Unverified users can sign up multiple times, but only the latest signup code will be active.
- Payload
- email (required)
- password (required)
- first_name (optional)
- last_name (optional)
- Possible responses
```python
201 (Created)
Content-Type: application/json
{
"email": "amelia.earhart@boeing.com"
"first_name": "Amelia",
"last_name": "Earhart",
}
400 (Bad Request)
Content-Type: application/json
{
"email": [
"This field may not be blank."
],
"password": [
"This field may not be blank."
]
}
{
"email": [
"Enter a valid email address."
]
}
{
"detail": "User with this Email address already exists."
}
```
**GET /api/accounts/signup/verify/?code=\<code\>**
When the user clicks the link in the verification email, the front end should call this endpoint to verify the user.
- Parameters
- code (required)
- Possible responses
```python
200 (OK)
Content-Type: application/json
{
"success": "User verified."
}
400 (Bad Request)
Content-Type: application/json
{
"detail": "Unable to verify user."
}
```
**POST /api/accounts/login**
Call this endpoint to log in a user. Use the authentication token in future calls to identify the user.
- Payload
- email (required)
- password (required)
- Possible responses
```python
200 (OK)
Content-Type: application/json
{
"token": "91ec67d093ded89e0a752f35188802c261899013"
}
400 (Bad Request)
Content-Type: application/json
{
"password": [
"This field may not be blank."
],
"email": [
"This field may not be blank."
]
}
{
"email": [
"Enter a valid email address."
]
}
401 (Unauthorized)
{
"detail": "Authentication credentials were not provided."
}
{
"detail": "Unable to login with provided credentials."
}
```
**GET /api/accounts/logout**
Call this endpoint to log out an authenticated user.
- HTTP Header
```python
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```
- Possible responses
```python
200 (OK)
Content-Type: application/json
{
"success": "User logged out."
}
401 (Unauthorized)
Content-Type: application/json
{
"detail": "Authentication credentials were not provided."
}
{
"detail": "Invalid token"
}
```
**POST /api/accounts/password/reset**
Call this endpoint to send an email to a user so they can reset their password. Similar to signup verification, the password reset email templates are found in `authemail/templates/authemail`. Override the default templates by placing your similarly-named templates in `your_app/templates/authemail`.
- Payload
- email (required)
- Possible responses
```python
201 (Created)
Content-Type: application/json
{
"email": "amelia.earhart@boeing.com"
}
400 (Bad Request)
Content-Type: application/json
{
"email": [
"This field may not be blank."
]
}
{
"email": [
"Enter a valid email address."
]
}
{
"detail": "Password reset not allowed."
}
```
**GET /api/accounts/password/reset/verify/?code=\<code\>**
When the user clicks the link in the password reset email, call this endpoint
to verify the password reset code.
- Parameters
- code (required)
- Possible responses
```python
200 (OK)
Content-Type: application/json
{
"success": "User verified."
}
400 (Bad Request)
Content-Type: application/json
{
"password": [
"This field may not be blank."
]
}
{
"detail": "Unable to verify user."
}
```
**POST /api/accounts/password/reset/verified**
Call this endpoint with the password reset code and the new password, to reset
the user's password. The front end should prompt the user for a confirmation
password and give feedback if the passwords don't match.
- Payload
- code (required)
- password (required)
- Possible responses
```python
200 (OK)
Content-Type: application/json
{
"success": "Password reset."
}
400 (Bad Request)
Content-Type: application/json
{
"password": [
"This field may not be blank."
]
}
{
"detail": "Unable to verify user."
}
```
**POST /api/accounts/email/change**
Call this endpoint to send a notification email to the previous email address
and a confirmation email to the new email address. Similar to signup and
password reset verification, the email change email templates are found in
`authemail/templates/authemail`. Override the default templates by placing
your similarly-named templates in `your_app/templates/authemail`.
- HTTP Header
```python
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```
- Payload
- email (required)
- Possible responses
```python
201 (Created)
Content-Type: application/json
{
"email": "amelia.earhart@boeing.com"
}
400 (Bad Request)
Content-Type: application/json
{
"email": [
"This field may not be blank."
]
}
{
"email": [
"Enter a valid email address."
]
}
{
"detail": "Email address already taken."
}
401 (Unauthorized)
Content-Type: application/json
{
"detail": "Authentication credentials were not provided."
}
{
"detail": "Invalid token"
}
```
**GET /api/accounts/email/change/verify/?code=\<code\>**
When the user clicks the link in the email change email, call this endpoint to
verify the email change code and, if appropriate, change the email address.
- Parameters
- code (required)
- Possible responses
```python
200 (OK)
Content-Type: application/json
{
"success": "Email address changed."
}
400 (Bad Request)
Content-Type: application/json
{
"detail": "Email address already taken."
}
{
"detail": "Unable to verify user."
}
```
**POST /api/accounts/password/change**
Call this endpoint to change a user's password.
- HTTP Header
```python
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```
- Payload
- password (required)
- Possible responses
```python
200 (OK)
Content-Type: application/json
{
"success": "Password changed."
}
400 (Bad Request)
Content-Type: application/json
{
"password": [
"This field may not be blank."
]
}
401 (Unauthorized)
Content-Type: application/json
{
"detail": "Authentication credentials were not provided."
}
{
"detail": "Invalid token"
}
```
**GET /api/accounts/users/me**
Call this endpoint after logging in and obtaining an authorization token to learn more about the user.
- HTTP Header
```python
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```
- Possible responses
```python
200 (OK)
Content-Type: application/json
{
"id": 1,
"email": "amelia.earhart@boeing.com",
"first_name": "Amelia",
"last_name": "Earhart",
}
401 (Unauthorized)
Content-Type: application/json
{
"detail": "Authentication credentials were not provided."
}
{
"detail": "Invalid token"
}
```
Django Packages
---------------------
- `django-rest-authemail` can be found on Django Packages at https://djangopackages.org/packages/p/django-rest-authemail/.
- `django-rest-authemail` can be found in the Django REST Framework Comparison Grid at https://djangopackages.org/grids/g/django-rest-framework/.
Inspiration and Ideas
---------------------
Inspiration and ideas for `django-rest-authemail` were derived from:
- [django-rest-framework](http://www.django-rest-framework.org/)
- [django-email-as-username](https://pypi.python.org/pypi/django-email-as-username/1.6.7)
- [django-registration](http://django-registration.readthedocs.org/en/latest/)
- [django-rest-auth](https://pypi.python.org/pypi/django-rest-auth)
- [tmdbsimple](https://pypi.python.org/pypi/tmdbsimple)
Raw data
{
"_id": null,
"home_page": "http://github.com/celiao/django-rest-authemail",
"name": "django-rest-authemail",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "django,python,rest,rest-framework,api,auth,authentication,email,user,username,registration,signup,login,logout,password,django-rest-framework,djangorestframework,django-registration,django-email-as-username",
"author": "Celia Oakley",
"author_email": "celia.oakley@alumni.stanford.edu",
"download_url": "https://files.pythonhosted.org/packages/c5/83/c6f5623641acd6cb3f47fc82186a2289334e5126c72dbd1c9f6ba6f87589/django-rest-authemail-2.1.7.tar.gz",
"platform": null,
"description": "django-rest-authemail\n=====================\n\n\n\n\n\n\n\n`django-rest-authemail` is a Django/Python application that provides a RESTful API interface for user signup and authentication. Email addresses are used for authentication, rather than usernames. Because the authentication user model is based on Django's `AbstractBaseUser` and is itself abstract, the model can be extended without the need for additional database tables. Token authentication allows the API to be accessed from a variety of front ends, including Django, React and AngularJS clients, and iOS and Android mobile apps.\n\n\nFeatures\n--------\n\n- API endpoints for signup, signup email verification, login, logout, password reset, password reset verification, password change, email change, and user detail.\n- Extensible abstract user model.\n- Perform password confirmation and other client-side validation on the front end for a better user experience.\n- Token authentication.\n- User models in the admin interface include inlines for signup and password reset codes.\n- An example project is included and contains example UI templates.\n- Version `2.0.5` and beyond\n\t- Supports and tested with Python 3.6, 3.7, and 3.8.\n\t- Supports and tested with Django 2.2.8, 2.2.13, 3.0, 3.1, and 3.2.\n\t- Supports and tested with Django REST Framework 3.11.2 and 3.12.4.\n- Version `1.10.2`\n\t- Supports and tested with Python 3.6 and 3.7.\n\t- Supports and tested with Django 1.11.17, 2.0, and 2.1.1.\n\t- Supports and tested with Django REST Framework 3.7.1 and 3.11.0.\n\n\nInstallation\n------------\n\n`django-rest-authemail` is available on the Python Package Index (PyPI) at https://pypi.python.org/pypi/django-rest-authemail.\n\nInstall `django-rest-authemail` using one of the following techniques.\n\n- Use pip. Note that particular versions of Django and the Django REST Framework may be installed.\n\n```\npip install django-rest-authemail\n```\n\n- Download the .tar.gz file from PyPI and install it yourself.\n- Download the [source from Github](http://github.com/celiao/django-rest-authemai) and install it yourself.\n\nIf you install it yourself, also install [Django](https://www.djangoproject.com/), the [Django REST Framework](http://www.django-rest-framework.org), and [requests](http://www.python-requests.org/en/latest).\n\nUsage\n-----\n\nCreate a Django project, if you haven't already. For example,\n\n```python\ndjango-admin startproject mysite\n```\n\nIn the `settings.py` file of your project, include `rest_framework` and `rest_framework.authtoken` in `INSTALLED_APPS`. Set the authentication scheme for the Django REST Framework to `TokenAuthentication`.\n\n```python\nmysite/settings.py\n----\n\nINSTALLED_APPS = [\n\t...\n\t'rest_framework',\n\t'rest_framework.authtoken',\n\t...\n]\n\nREST_FRAMEWORK = {\n\t'DEFAULT_AUTHENTICATION_CLASSES': (\n\t\t'rest_framework.authentication.TokenAuthentication',\n\t)\n}\n```\n\nOptionally, you may add an `AUTH_EMAIL_VERIFICATION` setting to specify whether to enable email verification for new users on account registration/signup. Setting this to `False` will automatically verify newly created users.\n\nCreate a Django application for your user data. For example,\n\n```python\npython manage.py startapp accounts\n```\n\nIn the `models.py` file of your application, extend `EmailAbstractUser`, add custom fields, and assign `objects` to `EmailUserManager()`. For example,\n\n```python\naccounts/models.py\n----\n\nfrom django.db import models\nfrom authemail.models import EmailUserManager, EmailAbstractUser\n\nclass MyUser(EmailAbstractUser):\n\t# Custom fields\n\tdate_of_birth = models.DateField('Date of birth', null=True, blank=True)\n\n\t# Required\n\tobjects = EmailUserManager()\n```\n\nIn the `settings.py` file of your project, include `authemail` and your application in `INSTALLED_APPS`. Set `AUTH_USER_MODEL` to the class of your user model. For example,\n\n```python\nmysite/settings.py\n----\n\nINSTALLED_APPS = [\n\t...\n\t'rest_framework',\n\t'rest_framework.authtoken',\n\t'authemail',\n\t'accounts',\n\t...\n]\n\nAUTH_USER_MODEL = 'accounts.MyUser'\n\n```\n\nIn the `admin.py` file of your project, extend `EmailUserAdmin` to add your custom fields. For example,\n\n```python\nmysite/admin.py\n----\n\nfrom django.contrib import admin\nfrom django.contrib.auth import get_user_model\nfrom authemail.admin import EmailUserAdmin\n\nclass MyUserAdmin(EmailUserAdmin):\n\tfieldsets = (\n\t\t(None, {'fields': ('email', 'password')}),\n\t\t('Personal Info', {'fields': ('first_name', 'last_name')}),\n\t\t('Permissions', {'fields': ('is_active', 'is_staff', \n\t\t\t\t\t\t\t\t\t 'is_superuser', 'is_verified', \n\t\t\t\t\t\t\t\t\t 'groups', 'user_permissions')}),\n\t\t('Important dates', {'fields': ('last_login', 'date_joined')}),\n\t\t('Custom info', {'fields': ('date_of_birth',)}),\n\t)\n\nadmin.site.unregister(get_user_model())\nadmin.site.register(get_user_model(), MyUserAdmin)\n```\n\n\nCreate the database tables with Django's `makemigrations`, `migrate`, and create a superuser with `createsuperuser`.\n\n```python\npython manage.py makemigrations\npython manage.py migrate\npython manage.py createsuperuser\n```\n\n\nCheck your setup by starting a Web server on your local machine:\n\n```python\npython manage.py runserver\n```\n\n\nDirect your browser to the `Django` `/admin` and log in.\n\n```python\n127.0.0.1:8000/admin\n```\n\nYou should see `Users`, `Tokens`, `Password reset codes`, `Signup codes`, and `Groups`. If you click on `Users`, you should see your superuser account.\n\nAdd the `authemail` API endpoints to your project's `urls.py` file. For example,\n\n```python\nmysite/urls.py\n----\n\nfrom django.contrib import admin\nfrom django.urls import include, path\n\nurlpatterns = [\n\tpath('admin/', admin.site.urls),\n\n\tpath('api/accounts/', include('authemail.urls')),\n]\n```\n\nWhen users signup or reset their password, they will be sent an email with a link and verification code. Include email settings as environment variables or in your project's `settings.py` file. For example,\n\n```python\nmysite/settings.py\n----\n\n# Email settings\n# https://docs.djangoproject.com/en/3.1/topics/email/\n# https://docs.djangoproject.com/en/3.1/ref/settings/#email-host\n\nimport os\n\nEMAIL_FROM = os.environ.get('AUTHEMAIL_DEFAULT_EMAIL_FROM') or '<YOUR DEFAULT_EMAIL_FROM HERE>'\nEMAIL_BCC = os.environ.get('AUTHEMAIL_DEFAULT_EMAIL_BCC') or '<YOUR DEFAULT_EMAIL_BCC HERE>'\n\nEMAIL_HOST = os.environ.get('AUTHEMAIL_EMAIL_HOST') or 'smtp.gmail.com'\nEMAIL_PORT = os.environ.get('AUTHEMAIL_EMAIL_PORT') or 587\nEMAIL_HOST_USER = os.environ.get('AUTHEMAIL_EMAIL_HOST_USER') or '<YOUR EMAIL_HOST_USER HERE>'\nEMAIL_HOST_PASSWORD = os.environ.get('AUTHEMAIL_EMAIL_HOST_PASSWORD') or '<YOUR EMAIL_HOST_PASSWORD HERE>'\nEMAIL_USE_TLS = True\nEMAIL_USE_SSL = False\n```\n\nTry out `authemail` API calls by firing up `python` and using the `authemail` wrapper methods (`runserver` should still be executing). For example,\n\n```python\npython\n>>> from authemail import wrapper\n>>> account = wrapper.Authemail()\n>>> first_name = 'Your first name'\n>>> last_name = 'Your last name'\n>>> email = 'your_email@gmail.com'\n>>> password = 'Your password'\n>>> response = account.signup(first_name=first_name, last_name=last_name,\n... email=email, password=password)\n```\n\nIn the `Django` `/admin`, you should see a new user (not verified) and a new signup code. You should receive an email at `your_email@gmail.com`. Use the code in the email to verify your email address using the wrapper (normally, the link in the email would point to the front end, which would issue the signup verify request to the API):\n\n```python\n>>> code = '7f31e7a515df266532df4e00e0cf1967a7de7d17'\n>>> response = account.signup_verify(code=code)\n```\n\nIn the `Django` `/admin`, the new user is now verified and the signup code is absent. The new user can now login and you can inspect the associated login token:\n\n```python\n>>> response = account.login(email=email, password=password)\n>>> account.token\n'a84d062c1b60a36e6740eb60c6f9da8d1f709322'\n```\n\nYou will find the same token for the user in the `Token` table in the `Django` `/admin`. Find out more information about the user (insert your token):\n\n```python\n>>> token = 'a84d062c1b60a36e6740eb60c6f9da8d1f709322'\n>>> response = account.users_me(token=token)\n>>> response\n{'id': 1, 'first_name': 'Your first name', 'last_name': 'Your last name', 'email': 'your_email@gmail.com'}\n```\n\nUse the authentication token to logout:\n\n```python\n>>> response = account.logout(token=token)\n>>> response\n{'success': 'User logged out.'}\n```\n\nPlay with password reset and change!\n\nDjango REST Framework Browsable API\n-----\n\nIf you are having trouble getting your code to execute, or are just curious, try out the Django REST Framework Browsable API. If you type an `authemail` API endpoint into your browser, the Browsable API should appear (`runserver` should still be executing). For example,\n\n```python\n127.0.0.1:8000/api/accounts/signup\n```\n\nEnter information in the HTML form fields of the Browsable API, e.g.:\n\n\n\nThen click on `POST`. You will either receive an error message to help in your debugging, or, if your signup was successful:\n\n\n\nTry out the other `authemail` API endpoints with the Django REST Framework Browsable API.\n\n\nFront End Example Project\n----\n\nMake `authemail` API calls from front end code. To get started, follow the steps in the`example_project` `README.md`. Enhance the Django code in the `example_project` or extend the concepts to React, AngularJS, iOS, and Android front ends.\n\nWhen calling endpoints from the front end that require authentication (`logout`, `password/change`, and `users/me`), include the authorization token key in the HTTP header. For example,\n\n```python\nAuthorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b\n```\n\nHere's an example using ``curl``,\n\n```python\ncurl -X GET 'http://127.0.0.1:8000/api/accounts/logout/' \\\n -H 'Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b'\n```\n\nWrapper\n-------\nA wrapper is available to access the Authemail API with Python code. First create an instance of the Authemail class, then call methods to access the API. There is a one-to-one mapping between the endpoints and instance methods. For example,\n\n```python\nmysite/views.py\n----\n\nfrom authemail import wrapper\n\naccount = wrapper.Authemail()\nresponse = account.signup(first_name=first_name, last_name=last_name,\n\temail=email, password=password)\n\nif 'detail' in response:\n\t# Handle error condition\nelse:\n\t# Handle good response\n```\n\nSee `example_project/views.py` for more sample usage.\n\n\nAuthemail API Endpoints\n-----------------------\nFor the endpoints that follow, the base path is shown as `/api/accounts`. This path is for example purposes. It can be customized in your project's `urls.py` file.\n\n**POST /api/accounts/signup**\n\nCall this endpoint to sign up a new user and send a verification email. Sample email templates are found in `authemail/templates/authemail`. To override the email templates, copy and modify the sample templates, or create your own, in `your_app/templates/authemail`.\n\nYour front end should handle password confirmation, and if desired, require the visitor to input their first and last names.\n\nUnverified users can sign up multiple times, but only the latest signup code will be active.\n\n- Payload\n \n - email (required)\n - password (required)\n - first_name (optional)\n - last_name (optional)\n\n- Possible responses\n\n```python\n201 (Created)\nContent-Type: application/json\n{\n\t\"email\": \"amelia.earhart@boeing.com\"\n\t\"first_name\": \"Amelia\", \n\t\"last_name\": \"Earhart\", \n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"email\": [\n\t\t\"This field may not be blank.\"\n\t], \n\t\"password\": [\n\t\t\"This field may not be blank.\"\n\t] \n}\n\n{\n\t\"email\": [\n\t\t\"Enter a valid email address.\"\n\t]\n}\n\n{\n\t\"detail\": \"User with this Email address already exists.\"\n}\n```\n\n**GET /api/accounts/signup/verify/?code=\\<code\\>**\n\nWhen the user clicks the link in the verification email, the front end should call this endpoint to verify the user.\n\n- Parameters\n\n - code (required)\n\n- Possible responses\n\n```python\n200 (OK)\nContent-Type: application/json\n{\n\t\"success\": \"User verified.\"\n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"detail\": \"Unable to verify user.\"\n}\n```\n\n**POST /api/accounts/login**\n\nCall this endpoint to log in a user. Use the authentication token in future calls to identify the user.\n\n- Payload\n\n - email (required)\n - password (required)\n\n- Possible responses\n\n\n```python\n200 (OK)\nContent-Type: application/json\n{\n\t\"token\": \"91ec67d093ded89e0a752f35188802c261899013\"\n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"password\": [\n\t\t\"This field may not be blank.\"\n\t], \n\t\"email\": [\n\t\t\"This field may not be blank.\"\n\t]\n}\n\n{\n\t\"email\": [\n\t\t\"Enter a valid email address.\"\n\t]\n}\n\n401 (Unauthorized)\n{\n\t\"detail\": \"Authentication credentials were not provided.\"\n}\n\n{\n\t\"detail\": \"Unable to login with provided credentials.\"\n}\n```\n\n**GET /api/accounts/logout**\n\nCall this endpoint to log out an authenticated user.\n\n- HTTP Header\n\n```python\nAuthorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b\n```\n\n- Possible responses\n\n```python\n200 (OK)\nContent-Type: application/json\n{\n\t\"success\": \"User logged out.\"\n}\n\n401 (Unauthorized)\nContent-Type: application/json\n{\n\t\"detail\": \"Authentication credentials were not provided.\"\n}\n\n{\n\t\"detail\": \"Invalid token\"\n}\n```\n\n**POST /api/accounts/password/reset**\n\nCall this endpoint to send an email to a user so they can reset their password. Similar to signup verification, the password reset email templates are found in `authemail/templates/authemail`. Override the default templates by placing your similarly-named templates in `your_app/templates/authemail`.\n\n- Payload\n\n - email (required)\n\n- Possible responses\n\n```python\n201 (Created)\nContent-Type: application/json\n{\n\t\"email\": \"amelia.earhart@boeing.com\"\n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"email\": [\n\t\t\"This field may not be blank.\"\n\t]\n}\n\n{\n\t\"email\": [\n\t\t\"Enter a valid email address.\"\n\t]\n}\n\n{\n\t\"detail\": \"Password reset not allowed.\"\n}\n```\n\n**GET /api/accounts/password/reset/verify/?code=\\<code\\>**\n\nWhen the user clicks the link in the password reset email, call this endpoint\nto verify the password reset code.\n\n- Parameters\n\n - code (required)\n\n- Possible responses\n\n```python\n200 (OK)\nContent-Type: application/json\n{\n\t\"success\": \"User verified.\"\n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"password\": [\n\t\t\"This field may not be blank.\"\n\t] \n}\n\n{\n\t\"detail\": \"Unable to verify user.\"\n}\n```\n\n**POST /api/accounts/password/reset/verified**\n\nCall this endpoint with the password reset code and the new password, to reset\nthe user's password. The front end should prompt the user for a confirmation\npassword and give feedback if the passwords don't match.\n\n- Payload\n\n - code (required)\n - password (required)\n\n- Possible responses\n\n```python\n200 (OK)\nContent-Type: application/json\n{\n\t\"success\": \"Password reset.\"\n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"password\": [\n\t\t\"This field may not be blank.\"\n\t] \n}\n\n{\n\t\"detail\": \"Unable to verify user.\"\n}\n```\n\n**POST /api/accounts/email/change**\n\nCall this endpoint to send a notification email to the previous email address\nand a confirmation email to the new email address. Similar to signup and\npassword reset verification, the email change email templates are found in\n`authemail/templates/authemail`. Override the default templates by placing\nyour similarly-named templates in `your_app/templates/authemail`.\n\n- HTTP Header\n\n```python\nAuthorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b\n```\n\n- Payload\n\n - email (required)\n\n- Possible responses\n\n```python\n201 (Created)\nContent-Type: application/json\n{\n\t\"email\": \"amelia.earhart@boeing.com\"\n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"email\": [\n\t\t\"This field may not be blank.\"\n\t] \n}\n\n{\n\t\"email\": [\n\t\t\"Enter a valid email address.\"\n\t] \n}\n\n{\n\t\"detail\": \"Email address already taken.\"\n}\n\n401 (Unauthorized)\nContent-Type: application/json\n{\n\t\"detail\": \"Authentication credentials were not provided.\"\n}\n\n{\n\t\"detail\": \"Invalid token\"\n}\n```\n\n**GET /api/accounts/email/change/verify/?code=\\<code\\>**\n\nWhen the user clicks the link in the email change email, call this endpoint to\nverify the email change code and, if appropriate, change the email address.\n\n- Parameters\n\n - code (required)\n\n- Possible responses\n\n```python\n200 (OK)\nContent-Type: application/json\n{\n\t\"success\": \"Email address changed.\"\n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"detail\": \"Email address already taken.\"\n}\n\n{\n\t\"detail\": \"Unable to verify user.\"\n}\n```\n\n**POST /api/accounts/password/change**\n\nCall this endpoint to change a user's password.\n\n- HTTP Header\n\n```python\nAuthorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b\n```\n\n- Payload\n\n - password (required)\n\n- Possible responses\n\n```python\n200 (OK)\nContent-Type: application/json\n{\n\t\"success\": \"Password changed.\"\n}\n\n400 (Bad Request)\nContent-Type: application/json\n{\n\t\"password\": [\n\t\t\"This field may not be blank.\"\n\t] \n}\n\n401 (Unauthorized)\nContent-Type: application/json\n{\n\t\"detail\": \"Authentication credentials were not provided.\"\n}\n\n{\n\t\"detail\": \"Invalid token\"\n}\n```\n\n**GET /api/accounts/users/me**\n\nCall this endpoint after logging in and obtaining an authorization token to learn more about the user.\n\n- HTTP Header\n\n```python\nAuthorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b\n```\n\n- Possible responses\n\n```python\n200 (OK)\nContent-Type: application/json\n{\n\t\"id\": 1,\n\t\"email\": \"amelia.earhart@boeing.com\",\n\t\"first_name\": \"Amelia\",\n\t\"last_name\": \"Earhart\",\n}\n\n401 (Unauthorized)\nContent-Type: application/json\n{\n\t\"detail\": \"Authentication credentials were not provided.\"\n}\n\n{\n\t\"detail\": \"Invalid token\"\n}\n```\n\n\nDjango Packages\n---------------------\n- `django-rest-authemail` can be found on Django Packages at https://djangopackages.org/packages/p/django-rest-authemail/.\n- `django-rest-authemail` can be found in the Django REST Framework Comparison Grid at https://djangopackages.org/grids/g/django-rest-framework/.\n\n\nInspiration and Ideas\n---------------------\nInspiration and ideas for `django-rest-authemail` were derived from:\n\n- [django-rest-framework](http://www.django-rest-framework.org/)\n- [django-email-as-username](https://pypi.python.org/pypi/django-email-as-username/1.6.7)\n- [django-registration](http://django-registration.readthedocs.org/en/latest/)\n- [django-rest-auth](https://pypi.python.org/pypi/django-rest-auth)\n- [tmdbsimple](https://pypi.python.org/pypi/tmdbsimple)\n",
"bugtrack_url": null,
"license": "",
"summary": "A RESTful API for user signup and authentication using email addresses",
"version": "2.1.7",
"split_keywords": [
"django",
"python",
"rest",
"rest-framework",
"api",
"auth",
"authentication",
"email",
"user",
"username",
"registration",
"signup",
"login",
"logout",
"password",
"django-rest-framework",
"djangorestframework",
"django-registration",
"django-email-as-username"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6e171029767c1bd902091ecee2ec31f247530730ea7ecc290484b1e39459fbf4",
"md5": "2c574588f81dc0288bda0142fa82d200",
"sha256": "ef8a6a8344d7f24af9b202c83b0634c053914c28ba62557fa58f1851b0170b24"
},
"downloads": -1,
"filename": "django_rest_authemail-2.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2c574588f81dc0288bda0142fa82d200",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 44827,
"upload_time": "2023-03-29T04:49:54",
"upload_time_iso_8601": "2023-03-29T04:49:54.673405Z",
"url": "https://files.pythonhosted.org/packages/6e/17/1029767c1bd902091ecee2ec31f247530730ea7ecc290484b1e39459fbf4/django_rest_authemail-2.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c583c6f5623641acd6cb3f47fc82186a2289334e5126c72dbd1c9f6ba6f87589",
"md5": "0b07f98cb5a18423dffec1490caed90d",
"sha256": "0256958c5067f481c9026d75ae3adae36dc0c9720d0a930f7dee475ddfb4a4b9"
},
"downloads": -1,
"filename": "django-rest-authemail-2.1.7.tar.gz",
"has_sig": false,
"md5_digest": "0b07f98cb5a18423dffec1490caed90d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 40896,
"upload_time": "2023-03-29T04:49:58",
"upload_time_iso_8601": "2023-03-29T04:49:58.406037Z",
"url": "https://files.pythonhosted.org/packages/c5/83/c6f5623641acd6cb3f47fc82186a2289334e5126c72dbd1c9f6ba6f87589/django-rest-authemail-2.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-29 04:49:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "celiao",
"github_project": "django-rest-authemail",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-rest-authemail"
}
JSON
