API

TouchPoint Authentication in External Applications

You may choose to utilize your TouchPoint system as an authentication method for external systems; this allows you and your congregants to access these systems without needing to remember additional usernames and passwords.

Validating Users

In order to identify the user to the external system, TouchPoint generates a one-time token which is sent to your external system. This token is unique to the user and expires after it is used or five minutes has passed.

When your system receives the token, it should call the TouchPoint Rest API method api/v1/Account/ValidateOneTimeLogin with the token as the body. This API will validate the token and if it is valid, return basic information about the user as JSON. If the token is invalid or expired, the API will return a 401 Unauthorized error:

curl --request POST \
--url https://mychurch.tpsdb.com/api/v1/Account/ValidateOneTimeLogin \
--header 'Authorization: PAT 12345678-9abc-def0-1234-56789abcdef0' \
--header 'Content-Type: text/plain' \
--data WYzKxHR1LEiu5Oq2c86REw

Note

This call utilizes Personal Access Token authentication to the TouchPoint API.

See also

Personal Access Tokens

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. You can also use a tool like Postman to make calls to test the system.

The information returned will be in the form:

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

Linking to External Systems

TouchPoint supports generating URLs with the one-time access token embedded in serveral places within the application.

Giving Pages

If you utilize an external giving system, you can configure the TouchPoint system to pass the token to the external system via the Redirect URL setting on the Giving Page setup. For instance:

  • https://my.giving.url/manage/{token} or

  • https://my.giving.url/manage/?token={token}

The {token} value will be populated by TouchPoint with the token generated for the user.

Mobile v3.x Banners

The link to which the user will be directed when they click on a banner in the mobile app can be configured to include the token by checking the “Authenticated Link” checkbox when setting up the banner.

External Systems

If you need to direct the user from an external system to TouchPoint to login and then return to the external system, you may formulate a URL with the return URL embedded in the query string. For instance:

https://mychurch.tpsdb.com/Account/Login?ReturnUrl=%2Fapi%2Fv1%2FAccount%2FRedirectWithCredentials%3Fdestination%3Dhttps%3A%2F%2Fmy.externalweb.church%2F%7Btoken%7D

When generating the URL, the ReturnUrl parameter is a URL encoded string that (before encoding) looks like:

/api/v1/Account/RedirectWithCredentials?destination=https://my.externalweb.church/{token}

Replace the my.externalweb.church parameter with your external system’s destination and the {token} parameter will be replaced with the one-time token.