Email Registration
==================

API Views
---------

There are two views used in the email registration / change workflow:

.. _register-email-view:

register-email
~~~~~~~~~~~~~~

.. autofunction:: rest_registration.api.views.register_email

.. _verify-email-view:

verify-email
~~~~~~~~~~~~

.. autofunction:: rest_registration.api.views.verify_email

Assuming that the Django REST Registration views are served at
``https://backend-host/api/v1/accounts/``
then the ``register_email``, ``verify_email`` views are served as:

*   ``https://backend-host/api/v1/accounts/register-email/``
*   ``https://backend-host/api/v1/accounts/verify-email/``

accordingly.

.. _register-email-verification-workflow:

Verification workflow
---------------------

Let's describe it by example.
We're assuming that:

-   the Django REST Registration views are served at
    ``https://backend-host/api/v1/accounts/``
-   you have :ref:`register-email-verification-enabled-setting` set to ``True``
    (this by default)
-   you configured :ref:`register-email-verification-url-setting` to be
    ``https://frontend-host/verify-email/``

Then the verification workflow looks as follows:

1.  The user who wants to register new email (which is currently equivalent
    to changing the e-mail) sends AJAX POST request to
    ``https://backend-host/api/v1/accounts/register-email/`` endpoint.
    Usually this happens via front-end aplication, which could be hosted
    on ``https://frontend-host/``.

2.  Assuming the registration was correct, The ``register_email`` endpoint
    will generate an e-mail which will contain an URL which the
    user should click to register new e-mail.
    the URL would be in a form:

    ``https://frontend-host/verify-email/?user_id=<user id>&email=<email>&timestamp=<timestamp>&signature=<signature>``

    (You can change the way the URL is generated by overriding
    :ref:`verification-url-builder-setting`)

3.  The frontend endpoint (which is not provided by Django REST Registration)
    ``https://frontend-host/verify-email/`` would receive following GET
    parameters:

    - ``user_id``
    - ``email``
    - ``timestamp``
    - ``signature``

    and then it should perform AJAX request to
    ``https://backend-host/api/v1/accounts/verify-email/``
    via HTTP POST with following JSON payload:

    .. code:: javascript

        {
            "user_id": "<user id>",
            "email": "<email>",
            "timestamp": "<timestamp>",
            "signature": "<signature>"
        }

    and then show a message to the user depending on the response from
    backend server.

Default serializers
-------------------

.. _default-register-email-serializer:

DefaultRegisterEmailSerializer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: rest_registration.api.serializers.DefaultRegisterEmailSerializer
   :members:

List of settings
----------------

These settings can be used to configure email registration workflow.
You should add them as keys (with values)
to your ``settings.REST_REGISTRATION`` dict.

.. jinja:: detailed_configuration__register_email
   :file: detailed_configuration/settings_fields.j2