Dokumentation der Loomio Server-API

/api/server0 ist für Vorgänge auf Serverebene vorgesehen. Nutze /api/user0 für Aktionen, die du mit einem Loomio-Benutzerkonto ausführst.

Nutze einen Serverschlüssel, um Konten zu erstellen und zu verwalten, Gruppen in der gesamten Installation zu finden und deren Mitgliedschaften und Rollen zu verwalten. Dafür sind weder ein Bot-Konto noch ein Benutzer-API-Schlüssel oder eine Mitgliedschaft in den Gruppen erforderlich. Für Benutzer-API-Schlüssel gelten weiterhin die Gruppenberechtigungen der jeweiligen Person.

Authentifizierung

Der Schlüssel wird über die Einstellung SERVER_API_KEY in der Serverumgebung festgelegt. create_env.sh erzeugt einen Schlüssel für neue Installationen.

Sende den Schlüssel als Bearer-Token:

curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users

Sende Zugangsdaten ausschließlich im Authorization-Header. API-Schlüssel in Abfragezeichenfolgen oder im Anfragetext werden abgelehnt.

Konten und Mitgliedschaften bereitstellen

Methode	Endpunkt	Zweck
`POST`	`/api/server0/users`	Ein Konto erstellen
`GET`	`/api/server0/groups`	Gruppen in der gesamten Installation finden
`GET`	`/api/server0/memberships`	Mitgliedschaften in einer Gruppe auflisten
`POST`	`/api/server0/memberships`	Mitglieder einladen oder eine vollständige Mitgliederliste synchronisieren
`PATCH`	`/api/server0/memberships/:id`	Admin- und Delegiertenrollen in einer Gruppe ändern
`DELETE`	`/api/server0/memberships/:id`	Eine Mitgliedschaft widerrufen

Die bestehenden Endpunkte zum Aktualisieren, Deaktivieren, Reaktivieren, Anonymisieren und Löschen von Konten werden weiter unten beschrieben.

Ein Konto erstellen

POST /api/server0/users

Sende ein user-Objekt mit dem Pflichtfeld email. Leerzeichen am Anfang und Ende von E-Mail-Adressen werden entfernt, und die Adressen werden in Kleinbuchstaben umgewandelt. Optionale Felder sind name, username und is_admin. Hier bezeichnet is_admin einen Admin der Instanz; Admin-Rollen für Gruppen werden über Mitgliedschaften verwaltet. Lasse username weg, um automatisch einen Benutzernamen zu erzeugen. Unbekannte Felder werden abgelehnt.

curl https://loomio.example.org/api/server0/users \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  --json '{
    "user": {
      "email": "ada@example.org",
      "name": "Ada Lovelace",
      "username": "ada",
      "is_admin": false
    }
  }'

Die Antwort ist HTTP 201 mit einem user-Objekt. Ungültige Felder oder eine bereits verwendete E-Mail-Adresse oder ein bereits verwendeter Benutzername führen zu HTTP 422. Beim Erstellen eines Kontos wird keine Einladung gesendet, die Person wird nicht angemeldet und ihre E-Mail-Adresse wird nicht als bestätigt markiert. Lade sie über den Mitgliedschaftsendpunkt in eine Gruppe ein, um eine Einladung über den üblichen Benachrichtigungsablauf zu senden.

Gruppen finden

GET /api/server0/groups

Liste alle Gruppen auf, die nicht gelöscht wurden, einschließlich privater Gruppen und Gruppen mit abgelaufenem Abonnement. Die Ergebnisse sind nach aufsteigender ID sortiert. Nutze limit (Standard- und Höchstwert 50) und offset (Standardwert 0), um die Ergebnisse seitenweise abzurufen.

curl 'https://loomio.example.org/api/server0/groups?limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY'

{
  "groups": [
    {
      "id": 123,
      "key": "examplegroup",
      "name": "Planning group",
      "handle": "planning",
      "parent_id": null,
      "group_privacy": "secret"
    }
  ],
  "meta": {
    "total": 1
  }
}

Mitgliedschaften auflisten

GET /api/server0/memberships?group_id=123

group_id ist erforderlich. Die Ergebnisse enthalten angenommene Mitgliedschaften und ausstehende Einladungen, sortiert nach aufsteigender Mitgliedschafts-ID. Widerrufene Mitgliedschaften sind ausgeschlossen. Nutze limit (Standard- und Höchstwert 50) und offset (Standardwert 0), um die Ergebnisse seitenweise abzurufen.

curl 'https://loomio.example.org/api/server0/memberships?group_id=123&limit=50&offset=0' \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY'

{
  "memberships": [
    {
      "id": 456,
      "group_id": 123,
      "user_id": 789,
      "user_email": "ada@example.org",
      "user_name": "Ada Lovelace",
      "admin": false,
      "delegate": false,
      "accepted_at": null,
      "pending": true
    }
  ],
  "meta": {
    "total": 1
  }
}

admin und delegate sind Gruppenrollen. accepted_at ist der Zeitstempel der Annahme oder null, solange eine Einladung aussteht. Dieser Endpunkt gibt keine Einladungstoken, Anmeldedaten oder Stimmen preis.

Mitglieder einladen oder synchronisieren

POST /api/server0/memberships

Sende die erforderliche group_id und ein erforderliches emails-Array. Standardmäßig werden dadurch die aufgeführten Personen hinzugefügt, die noch keine aktive Mitgliedschaft haben. Alle anderen Mitgliedschaften bleiben bestehen. Leerzeichen am Anfang und Ende von E-Mail-Adressen werden entfernt, die Adressen werden in Kleinbuchstaben umgewandelt und Duplikate werden entfernt. Für neue Adressen werden Konten und ausstehende Einladungen erstellt. Bereits vorhandene, bestätigte Mitglieder einer anderen aktiven Gruppe derselben Organisation werden automatisch aufgenommen, entsprechend dem Einladungsablauf der Benutzer-API.

curl https://loomio.example.org/api/server0/memberships \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "ada@example.org",
      "alex@example.org"
    ]
  }'

Um eine vollständige Mitgliederliste zu synchronisieren, setze remove_absent ausdrücklich auf true. Alle Personen, die in der Liste fehlen, werden aus dieser Gruppe und ihren Untergruppen entfernt. Ein leeres Array mit remove_absent: true entfernt alle Mitglieder, einschließlich der Gruppenadmins. Lasse remove_absent weg oder setze es auf false, wenn du nur Personen hinzufügen möchtest. Die älteren Werte 1 und 0 werden ebenfalls akzeptiert.

curl https://loomio.example.org/api/server0/memberships \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  --json '{
    "group_id": 123,
    "emails": [
      "ada@example.org"
    ],
    "remove_absent": true
  }'

{
  "added_emails": [],
  "removed_emails": [
    "alex@example.org"
  ]
}

Eine Wiederholung derselben Anfrage erstellt keine doppelten Mitgliedschaften und versendet keine erneuten Einladungen. Wenn du ein Mitglied mit widerrufener Mitgliedschaft erneut einlädst, erhält es wieder Zugriff auf die Gruppe, jedoch keine frühere Admin-Rolle. Neue Einladungen und Rollenänderungen nutzen den üblichen Benachrichtigungsablauf, wobei keine Person als ausführend erfasst wird.

Fehlende oder fehlerhaft formatierte E-Mail-Listen und ungültige boolesche Werte führen zu HTTP 400. Ein aufgeführtes deaktiviertes Konto führt zu HTTP 422; reaktiviere es ausdrücklich, bevor du es hinzufügst. Bei ungültigen Kontodaten, überschrittenen Abonnementgrenzen oder anderen Fehlern wird die gesamte Synchronisierung rückgängig gemacht, einschließlich neuer Konten und entfernter Mitgliedschaften. Das Hinzufügen erfordert eine aktive Gruppe und unterliegt weiterhin den Mitgliedergrenzen des Abonnements.

Mitgliedschaftsrollen aktualisieren

PATCH /api/server0/memberships/:id

Sende ein membership-Objekt mit einem oder beiden booleschen Feldern admin und delegate. Nicht angegebene Rollen bleiben unverändert. Unbekannte Felder werden abgelehnt; über den Endpunkt kannst du keine Mitgliedschaft übertragen, keine Einladung annehmen und keine Stimmgewichte ändern.

curl https://loomio.example.org/api/server0/memberships/456 \
  -X PATCH \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  --json '{
    "membership": {
      "admin": true,
      "delegate": false
    }
  }'

Gibt ein membership-Objekt mit denselben Feldern wie eine aufgelistete Mitgliedschaft zurück. Das Zuweisen einer Rolle erzeugt die übliche Rollenbenachrichtigung; eine erneute Anfrage mit unveränderter Rolle löst keine weitere Benachrichtigung aus. Rollenänderungen erfordern eine aktive Gruppe. Widerrufene Mitgliedschaften führen zu HTTP 404.

Eine Mitgliedschaft entfernen

DELETE /api/server0/memberships/:id

curl https://loomio.example.org/api/server0/memberships/456 \
  -X DELETE \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY'

Gibt {"success": true} zurück. Das Entfernen widerruft den Zugriff auf die Gruppe und ihre Untergruppen, einschließlich des Zugriffs auf Themen und der Stimmrechte in aktiven Abstimmungen. Das Konto wird dabei nicht gelöscht, andere Gruppen werden nicht verändert und der direkte Zugriff auf Threads bleibt bestehen. Eine wiederholte Entfernung ist erfolgreich. Du kannst Mitgliedschaften aus Gruppen mit abgelaufenem Abonnement entfernen; gelöschte Gruppen führen zu HTTP 404.

Benutzerobjekt

Antworten mit Benutzerdaten haben diese Struktur:

{
  "id": 123,
  "name": "Ada Lovelace",
  "username": "ada",
  "email": "ada@example.org",
  "is_admin": false,
  "active": true,
  "deactivated_at": null,
  "identities": [
    {
      "id": 456,
      "identity_type": "oauth",
      "uid": "external-123",
      "email": "ada@example.org",
      "name": "Ada Lovelace"
    }
  ]
}

Benutzerkonten auflisten

Liste alle Benutzerkonten auf der Loomio-Installation auf.

GET /api/server0/users

Beispiel

curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users

Gibt zurück:

{
  "users": []
}

Benutzerkonto anzeigen

Finde ein Benutzerkonto anhand seiner Loomio-Benutzer-ID oder externen Identität.

GET /api/server0/users/:id

GET /api/server0/users/identity/:identity_type/:uid

Beispiele

Anhand der Loomio-Benutzer-ID:

curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123

Anhand der externen Identität:

curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123

Gibt zurück:

{
  "user": {}
}

Benutzerkonto aktualisieren

Aktualisiere die Profilfelder eines Benutzerkontos, das du anhand seiner Loomio-Benutzer-ID oder externen Identität gefunden hast.

PATCH /api/server0/users/:id

PATCH /api/server0/users/identity/:identity_type/:uid

Parameter

Feld	Beschreibung
`name`	Anzeigename
`username`	Loomio-Benutzername
`email`	E-Mail-Adresse

Beispiele

Anhand der Loomio-Benutzer-ID:

curl -X PATCH \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"user":{"name":"Ada Lovelace","username":"ada","email":"ada@example.org"}}' \
  https://www.loomio.com/api/server0/users/123

Anhand der externen Identität:

curl -X PATCH \
  -H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"user":{"name":"Ada Lovelace","username":"ada","email":"ada@example.org"}}' \
  https://www.loomio.com/api/server0/users/identity/oauth/external-123

Gibt das aktualisierte Benutzerkonto zurück:

{
  "user": {}
}

Benutzerkonto deaktivieren

Deaktiviere ein Benutzerkonto, das du anhand seiner Loomio-Benutzer-ID oder externen Identität gefunden hast.

POST /api/server0/users/:id/deactivate

POST /api/server0/users/identity/:identity_type/:uid/deactivate

Beispiele

Anhand der Loomio-Benutzer-ID:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/deactivate

Anhand der externen Identität:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/deactivate

Gibt zurück:

{
  "success": true,
  "user": {}
}

Benutzerkonto reaktivieren

Reaktiviere ein deaktiviertes Benutzerkonto anhand seiner Loomio-Benutzer-ID oder externen Identität.

POST /api/server0/users/:id/reactivate

POST /api/server0/users/identity/:identity_type/:uid/reactivate

Beispiele

Anhand der Loomio-Benutzer-ID:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/reactivate

Anhand der externen Identität:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/reactivate

Rückgabe:

{
  "success": true,
  "user": {}
}

Personenbezogene Kontodaten entfernen

Dabei bleiben die Kommentare und andere von der Person erstellte Inhalte in ihren Gruppen erhalten. Bekannte personenbezogene Daten wie Name, Kurzbiografie, Profilfoto, E-Mail-Adresse, Anmeldedaten, Identitäten und aktive Sitzungen werden jedoch entfernt.

Dies ist die empfohlene Methode, um eine Person aus Loomio zu entfernen.

POST /api/server0/users/:id/redact

POST /api/server0/users/identity/:identity_type/:uid/redact

Beispiele

Anhand der Loomio-Benutzer-ID:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/redact

Anhand der externen Identität:

curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/redact

Rückgabe:

{
  "success": true
}

Benutzerkonto löschen

Das Löschen entfernt das Benutzerkonto und die von der Person erstellten Datensätze. Kommentare werden aus Threads und Stimmen aus Abstimmungen entfernt. Gruppen, Diskussionen, Abstimmungen und andere von der Person erstellte Datensätze können durch Datenbankverknüpfungen ebenfalls gelöscht werden.

Dabei werden umfangreiche Daten gelöscht. Es wird dringend empfohlen, stattdessen die personenbezogenen Kontodaten zu entfernen.

DELETE /api/server0/users/:id

DELETE /api/server0/users/identity/:identity_type/:uid

Beispiele

Anhand der Loomio-Benutzer-ID:

curl -X DELETE -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123

Anhand der externen Identität:

curl -X DELETE -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123

Rückgabe:

{
  "success": true
}

Einstellungen zur SSO-Profilsynchronisierung

Verwende diese Einstellungen, wenn ein anderes System die Loomio-Profilfelder verwaltet.

LOOMIO_DISABLE_EDIT_USER_PROFILE=1
# LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1

LOOMIO_DISABLE_EDIT_USER_PROFILE=1 verhindert, dass Personen diese Felder selbst bearbeiten:

Feld	Hinweise
`name`	Durch externe Synchronisierung verwaltet
`username`	Durch externe Synchronisierung verwaltet
`email`	Durch externe Synchronisierung verwaltet
`avatar_kind` / `uploaded_avatar`	Durch externe Synchronisierung verwaltet

Personen können weiterhin lokale Loomio-Felder wie short_bio und location bearbeiten.

LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1 aktualisiert name und email anhand der SSO-Anmeldedaten. Lass die Zeile auskommentiert oder die Variable ungesetzt, wenn ausschließlich ein externes Synchronisierungsskript diese Aktualisierungen vornehmen soll.

LOOMIO_SSO_FORCE_USER_ATTRS funktioniert weiterhin für bestehende Installationen. Die Einstellung verhindert sowohl die Bearbeitung durch die Personen selbst als auch die Aktualisierung von name und email bei der SSO-Anmeldung.

Diese Seite wurde maschinell übersetzt. Wenn ein Wort falsch oder unklar ist, schreib eine E-Mail an contact@loomio.org, und wir korrigieren es.