API authentication

With authentication, we are talking about proof of a property against an entity. Translated, this means that a request to the REST API must be authenticated. The sender must make it clear to ChurchTools that they can perform this action. In the browser, this is done by means of a Login. The user must enter a user name and password before they can perform an action in ChurchTools.

Authentication via the API can be done using a password or Login Token. In the following, we take a closer look at both methods using examples and explain which is most suitable and when.

User name and password #

It is possible to authenticate yourself using a user name and password. This makes sense if you are building an app that users can use individually. In other words, they have to sign up themselves.

The following request authenticates a user with ChurchTools:

POST /login HTTP/1.1
Host: http://beispielkirche.test/api
Content-Type: application/json

{
"username": "max",
"password": "superSecretPassword"
}

The endpoint POST /api/login accepts a user name and a password and logs the user in. In response, ChurchTools sends a session cookie (see “Session and cookies” below). This cookie can be used for follow-up requests to interact with the REST API.

Login token #

The second way to authenticate yourself is to send a Login token. This is also often called an API token. This token can be sent along with a request via the Authorization header: Authorization: Login <token>. If the request is not authorized, i.e. no valid session cookie has been sent, ChurchTools attempts to authenticate the request using the token.

The token is a long text string and is unique for each user. This string authenticates a ChurchTools user. The token can be retrieved either via the web interface or directly via the API.

Web: In ChurchTools, the token can be retrieved via a user’s profile.

API: The same token can also be found for a person via the endpoint GET /api/persons/<personId>/logintoken.

GET /persons/1/logintoken HTTP/1.1
Host: http://beispielkirche.test/api
Content-Type: application/json

Example: The ChurchTools app uses a combination of Login and Token. The user can log in to the app with a username and password. A session is created and the cookie is sent to the app. The app then immediately retrieves the person’s Login token via the API. The session cookie is sent along with further requests. If the session expires (usually after 1 day), a 401 Unauthorized is returned and a new valid session is created using the Login token. The token is simply attached to the next request, ChurchTools authenticates the request and creates a new session and a new cookie.

Session and cookie #

A session is created for each user in ChurchTools. If a request is sent to ChurchTools, it is advisable to always send a valid session cookie, if available. This cookie makes it possible to fall back on an existing pre-calculated state and thus speed up the entire request.

For each session, ChurchTools calculates the permissions for this user. This step is computationally intensive. If no session cookie is sent, ChurchTools would recalculate the permissions for each request, which takes time. You save time and gain performance if the request is sent with a valid session cookie.