API

Personal Access Tokens

TouchPoint’s Rest API supports the use of Personal Access Tokens (PAT) for authentication. This allows you to generate a token that can be used to authenticate with the API without needing to provide or store a username and password in the calling system. It also allows you to invalidate tokens at any time should the need arise.

The management of PATs is done through the Rest API itself; the initial authentication to generate the PAT supports all standard TouchPoint authentication methods; however, Basic authentication is the easiest and will be utilized in the examples below.

Creating a Personal Access Token

To create a Personal Access Token, you will need to create a POST request to the api/v1/Account/CreateUserAccessToken endpoint:

curl --request POST \
--url http://mychurch.tpsdb.com/api/v1/Account/CreateUserAccessToken \
--header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
--header 'Content-Type: text/plain' \

The response will be in the form:

{
        "personalAccessToken": "37402a24-c96e-4575-b063-fb41fbb28651",
        "expirationDate": null
}

You may optionally include an expiration date in the request body to set an expiration date for the token. The date should be sent as the plain-content text of the POST:

curl --request POST \
--url https://mychurch.tpsdb.com/api/v1/Account/CreateUserAccessToken \
--header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
--header 'Content-Type: text/plain' \
--data 2024-11-10T03:00:00Z

Deleting/Invalidating a Personal Access Token

To delete or invalidate a Personal Access Token, you will need to create a POST request to the /api/v1/Account/DeleteUserAccessToken endpoint, providing the token to delete as the plain-text content of the request:

curl --request POST \
--url https://mychurch.tpsdb.com/api/v1/Account/DeleteUserAccessToken \
--header 'Authorization: Basic dXNlcjpwYXNzd29yZA==' \
--header 'Content-Type: text/plain' \
--data 37402a24-c96e-4575-b063-fb41fbb28651

Impersonating Another User with Personal Access Tokens

Users with the Admin role can impersonate another user in the API, similar to the Impersonate feature on the web. This impersonation is only available via Personal Access Token (PAT) authentication.

To impersonate another user, add the following header to your API request:

x-on-behalf-of: {{person id to impersonate}}

For example:

curl --request GET \
--url https://mychurch.tpsdb.com/api/v1/Account/RedirectWithCredentials/?destination=www.google.com \
--header 'Authorization: PAT 37402a24-c96e-4575-b063-fb41fbb28651' \
--header 'x-on-behalf-of: 12345'

This will execute the API request as if it were made by the person with ID 12345. If the user has multiple User accounts for the given PeopleId, then the first one (by ID) will be used.

Important

  • The Personal Access Token must belong to a user with Admin rights

  • To impersonate a user with the Finance role, the PAT owner must also have the Finance role

  • This feature allows for programmatic impersonation in API workflows while maintaining proper security controls