{"id":7252,"date":"2024-02-14T17:20:51","date_gmt":"2024-02-14T15:20:51","guid":{"rendered":"https:\/\/leogeracademy.hestia.wpspace.me\/?post_type=docs&p=7252"},"modified":"2024-10-31T16:35:00","modified_gmt":"2024-10-31T14:35:00","password":"","slug":"0-api-authentifizierung","status":"publish","type":"docs","link":"https:\/\/staging.churchtools.academy\/de\/help\/system-einstellungen\/api\/0-api-authentifizierung\/","title":{"rendered":"API Authentifizierung"},"content":{"rendered":"\n

Bei Authentitifizierung sprechen wir von einem Nachweis einer Eigenschaft gegen\u00fcber einer Entit\u00e4t. \u00dcbersetzt hei\u00dft das, dass ein Request an die REST API authentifiziert werden muss. Der Absender muss ChurchTools klar machen, dass er diese Aktion ausf\u00fchren kann. Im Browser passiert das mittlels eines Login. Der Nutzer muss einen Benutzernamen und ein Passwort angeben, bevor er eine Aktion in ChurchTools durchf\u00fchren kann.<\/p>\n\n\n\n

Die Authentifizierung \u00fcber die API kann mittels Passwort oder Login Token passieren. Wir schauen uns im Folgenden beide Verfahren anhand von Beispielen  genauer an und erkl\u00e4ren, welche wann am besten geeignet ist.<\/p>\n\n\n\n

Benutzername und Passwort<\/h3>\n\n\n\n

Es ist m\u00f6glich, dass man sich mittels Benutzernamen und Passwort authentifiziert. Dies ist sinnvoll, wenn man eine App baut, die Nutzer individuell nutzen k\u00f6nnen. Sprich, sie m\u00fcssen sich selber anmelden.<\/p>\n\n\n\n

Folgender Request authentifiziert einen Nutzer mit ChurchTools:<\/p>\n\n\n\n

POST \/login HTTP\/1.1<\/code>
Host: http:\/\/churchtools.test\/api<\/code>
Content-Type: application\/json<\/code>

{<\/code>
 \"username\": \"max\",<\/code>
 \"password\": \"superGeheimesPasswort\"<\/code>
}<\/code><\/p>\n\n\n\n

Der Endpoint POST \/api\/login<\/code> nimmt einen username<\/code> und ein password<\/code> entgegen und loggt den Benutzer ein. Als Antwort schickt ChurchTools ein Session-Cookie mit (lies dazu „Cookies & Session“ weiter unten). Dieser Cookie kann f\u00fcr Folgerequests verwendet werden, um mit der REST API zu interagieren.<\/p>\n\n\n\n

Login Token<\/h3>\n\n\n\n

Die zweite Variante, um sich zu authentifizieren, ist, einen Login Token mitzuschicken. Auch des \u00f6fteren API Token genannt. Dieser Token kann \u00fcber den Authorization Header bei einem Request mitgeschickt werden: Authorization: Login <token><\/code> (Bei \u00e4lteren ChurchTools Versionen war dies \u00fcber  den Query Parameter login_token=<token><\/code> m\u00f6glich). Sollte der Request unautorisiert sein, d.h. es wurde kein g\u00fcltiges Session-Cookie mitgeschickt, versucht ChurchTools den Request anhand des Tokens zu authentifizieren.<\/p>\n\n\n\n

Der Token ist ein langer Textstring und f\u00fcr jeden Nutzer individuell. Dieser String authentifiziert einen ChurchTools-User. Der Token kann entweder \u00fcber die Weboberfl\u00e4che abgerufen werden oder \u00fcber die API direkt.<\/p>\n\n\n\n

Web:<\/strong> In ChurchTools kann der Token unter Personen & Gruppen > Personenliste > „Person A“ > Berechtigungen > Login-Token<\/em> abgerufen werden.<\/p>\n\n\n\n

\"\"<\/a><\/figure>\n\n\n\n

API:<\/strong> Derselbe Token kann f\u00fcr eine Person auch \u00fcber den Endpoint GET \/api\/persons\/<personId>\/logintoken gefunden werden.<\/p>\n\n\n\n

GET \/persons\/1\/logintoken HTTP\/1.1
Host: http:\/\/churchtools.test\/api
Content-Type: application\/json<\/p>\n\n\n\n

Beispiel:<\/strong> Die ChurchTools-App nutzt eine Kombination aus Login und Token. Der Benutzer kann sich mit Benutzernamen und Passwort in der App einloggen. Dabei wird eine Session erstellt und das Cookie an die App geschickt. Die holt sich im Anschluss sofort den Login Token der Person \u00fcber die API. Das Session-Cookie wird bei weiteren Requests mitgeschickt. Sollte die Session auslaufen (i.d.R. nach 1 Tag) wird ein 401 Unauthorized<\/code> zur\u00fcckgegeben und nun wird mittels des Login Token eine neue g\u00fcltige Session erstellt. Der Token wird dabei einfach beim n\u00e4chsten Request angeh\u00e4ngt und ChurchTools authentifiziert den Request und erstellt eine neue Session und ein neues Cookie.<\/p>\n\n\n\n

Session und Cookie<\/h2>\n\n\n\n

In ChurchTools wird f\u00fcr jeden Nutzer eine Session erstellt. Sollte ein Request an ChurchTools gesendet werden, ist es ratsam immer ein g\u00fcltiges Session Cookie mitzuschicken, sofern vorhanden. Dieses Cookie erlaubt es, auf einen bestehenden schon vorkalkulierten State zur\u00fcckzugreifen und somit den ganzen Request zu beschleunigen.<\/p>\n\n\n\n

F\u00fcr jede Session berechnet ChurchTools die Berechtigungen f\u00fcr diesen Nutzer. Dieser Schritt ist rechenintensiv. Wird kein Session-Cookie mitgeschickt, w\u00fcrde ChurchTools die Berechtigungen bei jedem Request neu berechnen und das erfordert Zeit. Du sparst dir Zeit und gewinnst an Performance, wenn der Request mit einem g\u00fcltigen Session-Cookie geschickt wird.<\/p>\n","protected":false},"excerpt":{"rendered":"

Bei Authentitifizierung sprechen wir von einem Nachweis einer Eigenschaft gegen\u00fcber einer Entit\u00e4t. \u00dcbersetzt hei\u00dft das, dass ein Request an die REST API authentifiziert werden muss. Der Absender muss ChurchTools klar machen, dass er diese Aktion ausf\u00fchren kann. Im Browser passiert das mittlels eines Login. Der Nutzer muss einen Benutzernamen und ein Passwort angeben, bevor er […]<\/p>\n","protected":false},"author":7,"featured_media":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_acf_changed":false,"footnotes":""},"doc_category":[370],"doc_tag":[268,269],"knowledge_base":[346],"class_list":["post-7252","docs","type-docs","status-publish","hentry","doc_category-api","doc_tag-inhalt-veraltet","doc_tag-screenshot-veraltet","knowledge_base-system-einstellungen"],"acf":[],"year_month":"2026-06","word_count":578,"total_views":"1346","reactions":{"happy":"0","normal":"0","sad":"2"},"author_info":{"name":"Victoria Weidemann","author_nicename":"vweidemann","author_url":"https:\/\/staging.churchtools.academy\/de\/author\/vweidemann\/"},"doc_category_info":[{"term_name":"API","term_url":"https:\/\/staging.churchtools.academy\/de\/help\/system-einstellungen\/api\/"}],"doc_tag_info":[{"term_name":"Inhalt veraltet","term_url":"https:\/\/staging.churchtools.academy\/de\/docs-tag\/inhalt-veraltet\/"},{"term_name":"Screenshot veraltet","term_url":"https:\/\/staging.churchtools.academy\/de\/docs-tag\/screenshot-veraltet\/"}],"knowledge_base_info":[{"term_name":"System-Einstellungen","term_url":"https:\/\/staging.churchtools.academy\/de\/help\/system-einstellungen\/","term_slug":"system-einstellungen"}],"knowledge_base_slug":["system-einstellungen"],"_links":{"self":[{"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/docs\/7252","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/types\/docs"}],"author":[{"embeddable":true,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/users\/7"}],"replies":[{"embeddable":true,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/comments?post=7252"}],"version-history":[{"count":4,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/docs\/7252\/revisions"}],"predecessor-version":[{"id":17231,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/docs\/7252\/revisions\/17231"}],"wp:attachment":[{"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/media?parent=7252"}],"wp:term":[{"taxonomy":"doc_category","embeddable":true,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/doc_category?post=7252"},{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/doc_tag?post=7252"},{"taxonomy":"knowledge_base","embeddable":true,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/knowledge_base?post=7252"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}