Token Authentication
====================

Churches using TouchPoint can choose to enable external giving links, in order to direct donors to a giving
site outside of TouchPoint. In order to identify the donor in the web app that receives the external link,
a token parameter should be added to the link. For example,

* `https://my.giving.url/manage/{token}` or
* `https://my.giving.url/manage/?token={token}`

The ``{token}`` value will be populated by TouchPoint with a one-time link ID which expires in five minutes.
The receiving web app can then authenticate the user by querying the Push Post API method
``API/Authenticate/OneTimeLink/{token}``. You should also include in the giving URL the TouchPoint database name or
identify the user's TouchPoint database name from the ``Referer`` HTTP header. This API will validate the
token and if it is valid, returns basic information about the user as JSON::

    curl -X POST -H "Authorization: Basic
    YXR1c3R1cjpNeUPwaVBhc3N3b3JkVG9SdWx1VGh1bUFsbA=="  \
        "https://sandbox.tpsdb.com/API/Authenticate/OneTimeLink/Srux6hAuh0XDg9kPS3xI"

.. important::

    The example above shows using curl, a command line tool for transferring data using various URL protocols.
    This tool comes on a Mac and can be downloaded for Windows.


The information returned will be in the form::

    {
    "peopleId": 3194991,
    "firstName": "John",
    "preferredName": null,
    "lastName": "Doe",
    "emailAddress": "johnd@example.com",
    "emailAddress2": null,
    "campusId": 4
    }

**Note: Once the Authenticate/OneTimeLink call has been made, the token immediately expires and
cannot be used again.**