.. include:: /global.inc
.. include:: /banner.rst


Authentication
=================================================

Every request to the CFT API must include an application-level API key, to
verify that the client application is authorised to make the given request.

Additionally, requests to view or change user data require a user-level API key,
to ensure that the user has given permission to that specific application.

Both keys are 43-character alphanumeric strings.

.. warning:: API and app keys should be kept secret; please do not send them via
    unencrypted email or store them in version control.

If you send a request without valid authentication data, you will receive an
HTTP 403 forbidden response:

.. code-block:: sh

    $ curl -i "https://app.coolfarmtool.org/api/v1/farm/"
    HTTP/1.1 403 FORBIDDEN

.. code-block:: sh

    $ curl -I \
        -H "X-Api-Authorization: kS9UayP3WU7cLQHi5XUW9GylaToRcUtCuY12MPCyyb0" \
        -H "X-Api-App-Authorization: OWyHsuoAk74FLDGIGqrgWVBsffG32ndAhsyO1jeuU34" \
        "https://app.coolfarmtool.org/api/v1/farm/"
    HTTP/1.0 200 OK

Application-level API keys
--------------------------------------------

Request an API key for your application by contacting `the Cool Farm Alliance
<info@coolfarmtool.org>`_ -- or, if you are running your own instance, log in to
the admin area, then click "Api" |rarr| "Applications" |rarr| "Add"

Include your application API key in requests as an ``X-API-APP-Authorization``
header (example above), or an ``api_app_key`` request parameter .

User-level API keys
--------------------------------------------

Each Cool Farm Tool user is assigned a unique API key. Users can look up their
API key on the "Help" page once logged in, and provide it to your application.

Include the user's API key in requests as an ``X-API-Authorization`` header
(example above), or an ``api_key`` request parameter.

Applications can retrieve a user's API key by sending a username and password to
:http:post:`/user/key/`.

Registering a new account
--------------------------------------------

If the user does not have a CFT account already, you can assist them in creating
one by sending details to pre-fill on the registration form.

.. http:get:: /account/register/

    You can pre-fill details for the registration form by providing query
    parameters named according to the existing HTML form fields.

    .. note::

        This URL must be opened in the user's browser in order to complete the
        registration process; a server-side or AJAX request to
        ``/account/register/`` will likely not work. If you need to have
        information returned, use the ``callback`` parameter

    :form str username: desired username
    :form str email: user email address
    :form str callback: URL to send API key of new user after activation
    :form str app_id: numeric ID of your application. Required for ``callback``
    :form str hash: SHA256 hash of app key concatenated with ``callback``, required for ``callback``

    **Example request**

    .. sourcecode:: http

        GET /account/register/ HTTP/1.1
        Host: app.coolfarmtool.org
        Accept: application/json
        X-APP-Authorization: ...

        username=test&email=test@example.com&callback=https://example.com/cft&hash=a4337bc45a8fc544c03f52dc550cd6e1e87021bc896588bd79e901e2&app_id=1

    **Example response**

    .. sourcecode:: http

        HTTP/1.1 302 FOUND
        Set-Cookie: csrftoken=...; ... sessionid=...; ...
        Content-Type: text/html; charset=utf-8
        Location: ...

    :statuscode 400: missing or incorrect form data