{"id":7252,"date":"2026-08-03T09:00:00","date_gmt":"2026-08-03T08:00:00","guid":{"rendered":"https:\/\/churchtools.academy\/?post_type=docs&#038;p=7252"},"modified":"2026-08-24T12:48:02","modified_gmt":"2026-08-24T11:48:02","password":"","slug":"api-authentifizierung","status":"publish","type":"docs","link":"https:\/\/staging.churchtools.academy\/de\/help\/system-einstellungen\/api\/api-authentifizierung\/","title":{"rendered":"API Authentifizierung"},"content":{"rendered":"\n<p class=\"wp-block-paragraph\">Bei Authentifizierung 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 klarmachen, dass er diese Aktion ausf\u00fchren kann. Im Browser passiert das mittels 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<p class=\"wp-block-paragraph\">Die Authentifizierung \u00fcber die API kann mittels Passwort oder Login-Token passieren. Wir erkl\u00e4ren dir im Folgenden beide Verfahren anhand von Beispielen genauer und zeigen dir, wann welches am besten geeignet ist.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Benutzername und Passwort<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Die erste Variante mittels Benutzernamen und Passwort ist sinnvoll, wenn du z. B. eine App baust, die individuell genutzt werden kann. In diesem Fall m\u00fcssen sich die Nutzer also selbst einloggen.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Folgender Request authentifiziert einen Nutzer mit ChurchTools:<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><code>POST \/login HTTP\/1.1<\/code><br><code>Host: http:\/\/meine-gemeinde.test\/api<\/code><br><code>Content-Type: application\/json<\/code><br><br><code>{<\/code><br><code>&nbsp;\"username\": \"max\",<\/code><br><code>&nbsp;\"password\": \"superGeheimesPasswort\"<\/code><br><code>}<\/code><\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Der Endpoint <code>POST \/api\/login<\/code> nimmt einen <code>Benutzernamen<\/code> und ein P<code>asswort<\/code> entgegen und loggt den Benutzer ein. Als Antwort schickt ChurchTools ein Session-Cookie mit (lies dazu \u201eSession und Cookies\u201c weiter unten). Dieser Cookie kann f\u00fcr Folgerequests verwendet werden, um mit der REST API zu interagieren.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Login-Token<\/h3>\n\n\n\n<p class=\"wp-block-paragraph\">Die zweite Variante ist, einen Login-Token (auch: API-Token) mitzuschicken. Dieser Token kann \u00fcber den Authorization-Header bei einem Request mitgeschickt werden: <code>Authorization: Login &lt;token><\/code>. Sollte der Request nicht autorisiert sein, d.\u00a0h. es wurde kein g\u00fcltiges Session-Cookie mitgeschickt, versucht ChurchTools den Request anhand des Tokens zu authentifizieren.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Der Token ist ein langer Textstring und f\u00fcr jeden Nutzer individuell. Dieser String authentifiziert einen ChurchTools-Benutzer. Der Token kann entweder \u00fcber die Web-Oberfl\u00e4che abgerufen werden oder \u00fcber die API direkt.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>Web:<\/strong> In ChurchTools kann der Token \u00fcber das Profil eines Nutzers abgerufen werden.<\/p>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>API:<\/strong> Derselbe Token kann f\u00fcr eine Person auch \u00fcber den Endpoint GET <code>\/api\/persons\/&lt;personId&gt;\/logintoken<\/code> gefunden werden.<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>GET \/persons\/1\/logintoken HTTP\/1.1<br>Host: http:\/\/meine-gemeinde.test\/api<br>Content-Type: application\/json<\/code><\/pre>\n\n\n\n<p class=\"wp-block-paragraph\"><strong>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. <\/p>\n\n\n\n<p class=\"wp-block-paragraph\">Das Session-Cookie kann bei weiteren Requests mitgeschickt werden, ist f\u00fcr die Nutzung der REST-API aber nicht n\u00f6tig, da die REST-API standardm\u00e4\u00dfig ohne Session arbeitet. Sollte die Session auslaufen (i.\u00a0d.\u00a0R. nach 1 Tag) wird ein <code>401 Unauthorized<\/code> zur\u00fcckgegeben und nun wird mittels des Login-Tokens eine neue g\u00fcltige Session erstellt. Der Token wird dabei einfach beim n\u00e4chsten Request angeh\u00e4ngt, ChurchTools authentifiziert den Request und erstellt eine neue Session und ein neues Cookie.<\/p>\n\n\n\n<aside class=\"wp-block-group ct-box ct-box-blue has-background is-vertical is-layout-flex wp-container-core-group-is-layout-1ccdadb1 wp-block-group-is-layout-flex\" style=\"border-radius:8px;border-left-color:#3e70ce;border-left-width:0.5rem;background-color:#f3f5f7;margin-top:var(--wp--preset--spacing--60);margin-bottom:var(--wp--preset--spacing--60)\">\n<p class=\"wp-block-paragraph\" style=\"margin-top:0.5rem;margin-right:0.5rem;margin-bottom:0rem;margin-left:0.5rem\"><strong>Hinweis<\/strong><\/p>\n\n\n\n<p class=\"wp-block-paragraph\" style=\"margin-top:0rem;margin-right:0.5rem;margin-bottom:0.5rem;margin-left:0.5rem\">Login-Tokens erzeugen bei REST-API-Aufrufen standardm\u00e4\u00dfig keine Session. Falls eine Session ben\u00f6tigt wird, kann diese mit dem GET-Parameter <code>with_session=true<\/code> angefordert werden.<\/p>\n<\/aside>\n\n\n\n<h2 class=\"wp-block-heading\">OAuth-Anwendungen mit API-Zugriff<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">OAuth-Anwendungen k\u00f6nnen mit ausdr\u00fccklicher Freigabe (Scope: <code>api<\/code>) jetzt auf die ChurchTools-API zugreifen \u2013 selbstverst\u00e4ndlich nur im Rahmen der Berechtigungen des angemeldeten Benutzers. Damit sind nun eigene Applikationen denkbar, die den Login via ChurchTools erm\u00f6glichen und mit den Berechtigungen des Nutzers Daten aus ChurchTools laden.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Session und Cookie<\/h2>\n\n\n\n<p class=\"wp-block-paragraph\">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<aside class=\"wp-block-group ct-artikel-zum-weiterlesen has-background is-layout-constrained wp-container-core-group-is-layout-79a8db7e wp-block-group-is-layout-constrained\" style=\"border-radius:8px;background-color:#f9fafb;margin-top:24px;margin-bottom:24px;padding-top:32px;padding-right:24px;padding-bottom:32px;padding-left:24px\">\n<h2 class=\"wp-block-heading has-medium-font-size\">Artikel zum Weiterlesen<\/h2>\n\n\n\n<ul class=\"wp-block-list\">\n<li><a href=\"https:\/\/staging.churchtools.academy\/de\/help\/system-einstellungen\/api\/uberblick-api\/\" type=\"docs\" id=\"7251\">\u00dcberblick API<\/a><\/li>\n\n\n\n<li><a type=\"docs\" href=\"https:\/\/staging.churchtools.academy\/de\/help\/system-einstellungen\/api\/api-dokumentation\/\" id=\"7253\">API Dokumentation<\/a><\/li>\n<\/ul>\n<\/aside>\n","protected":false},"excerpt":{"rendered":"<p>Bei Authentifizierung 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 klarmachen, dass er diese Aktion ausf\u00fchren kann. Im Browser passiert das mittels eines Login. Der Nutzer muss einen Benutzernamen und ein Passwort angeben, bevor er eine [&hellip;]<\/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"],"pp_statuses_selecting_workflow":false,"pp_workflow_action":"current","pp_status_selection":"publish","pp_force_visibility":null,"pp_subpost_visibility":null,"pp_inherited_force_visibility":null,"pp_inherited_subpost_visibility":null,"acf":[],"year_month":"2026-08","word_count":559,"total_views":"3950","reactions":{"happy":"1","normal":"0","sad":"3"},"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":20,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/docs\/7252\/revisions"}],"predecessor-version":[{"id":90129,"href":"https:\/\/staging.churchtools.academy\/de\/wp-json\/wp\/v2\/docs\/7252\/revisions\/90129"}],"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}]}}