Documentatie van de Loomio Server-API
/api/server0 is voor bewerkingen op serverniveau. Gebruik /api/user0 voor gebruikersgerichte acties die je uitvoert met een Loomio-gebruikersaccount.
Gebruik één serversleutel om accounts aan te maken en te beheren, groepen in de hele installatie te vinden en hun lidmaatschappen en rollen te beheren. Je hebt geen botaccount, API-sleutel voor een gebruiker of lidmaatschap van de groepen nodig. API-sleutels voor gebruikers blijven de groepsrechten van de gebruiker volgen.
Authenticatie
De sleutel is de instelling SERVER_API_KEY in de serveromgeving. create_env.sh genereert er een voor nieuwe installaties.
Stuur de sleutel als een bearer-token:
curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users
Stuur inloggegevens alleen in de Authorization-header. API-sleutels in querystrings of de inhoud van verzoeken worden geweigerd.
Accounts en lidmaatschappen aanmaken en beheren
| Methode | Endpoint | Doel |
|---|---|---|
POST |
/api/server0/users |
Een account aanmaken |
GET |
/api/server0/groups |
Groepen in de hele installatie vinden |
GET |
/api/server0/memberships |
Lidmaatschappen in een groep opvragen |
POST |
/api/server0/memberships |
Leden uitnodigen of een volledige ledenlijst synchroniseren |
PATCH |
/api/server0/memberships/:id |
De groepsrollen admin en afgevaardigde wijzigen |
DELETE |
/api/server0/memberships/:id |
Eén lidmaatschap intrekken |
De bestaande endpoints voor het bijwerken, deactiveren, reactiveren, anonimiseren en verwijderen van accounts worden hieronder beschreven.
Een account aanmaken
POST /api/server0/users
Verstuur een user-object met een verplicht veld email. Spaties aan het begin en einde van e-mailadressen worden verwijderd en de adressen worden omgezet naar kleine letters. Optionele velden zijn name, username en is_admin. Hier betekent is_admin een admin van de installatie; adminrollen voor groepen worden via lidmaatschappen beheerd. Laat username weg om automatisch een gebruikersnaam te genereren. Onbekende velden worden geweigerd.
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
}
}'
Het antwoord is HTTP 201 met een user-object. Ongeldige velden of een e-mailadres of gebruikersnaam die al in gebruik is, leveren HTTP 422 op. Bij het aanmaken van een account wordt geen uitnodiging verstuurd, wordt de persoon niet ingelogd en wordt het e-mailadres niet als geverifieerd gemarkeerd. Nodig de persoon via het lidmaatschapsendpoint uit voor een groep om een uitnodiging via de normale meldingsprocedure te versturen.
Groepen vinden
GET /api/server0/groups
Vraag alle groepen op die niet zijn verwijderd, inclusief privégroepen en groepen met verlopen abonnementen. De resultaten worden gesorteerd op oplopend ID. Gebruik limit (standaard en maximaal 50) en offset (standaard 0) om ze per pagina op te vragen.
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
}
}
Lidmaatschappen opvragen
GET /api/server0/memberships?group_id=123
group_id is verplicht. De resultaten bevatten geaccepteerde lidmaatschappen en openstaande uitnodigingen, gesorteerd op oplopend lidmaatschaps-ID. Ingetrokken lidmaatschappen worden niet opgenomen. Gebruik limit (standaard en maximaal 50) en offset (standaard 0) voor paginering.
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 en delegate zijn groepsrollen. accepted_at is het tijdstip van acceptatie, of null zolang een uitnodiging openstaat. Dit endpoint geeft geen uitnodigingstokens, inloggegevens of stemmen vrij.
Leden uitnodigen of synchroniseren
POST /api/server0/memberships
Verstuur de verplichte velden group_id en de array emails. Standaard worden hiermee de vermelde personen toegevoegd die nog geen actief lidmaatschap hebben; alle anderen blijven lid. Spaties aan het begin en einde van e-mailadressen worden verwijderd, de adressen worden omgezet naar kleine letters en dubbele adressen worden verwijderd. Voor nieuwe adressen worden accounts en openstaande uitnodigingen aangemaakt. Bestaande geverifieerde leden van een andere actieve groep in dezelfde organisatie worden automatisch geaccepteerd, net als bij de uitnodigingsprocedure van de gebruikers-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"
]
}'
Stel remove_absent expliciet in op true om een volledige ledenlijst te synchroniseren. Iedereen die niet op de lijst staat, wordt uit die groep en de bijbehorende subgroepen verwijderd. Een lege array met remove_absent: true verwijdert iedereen, inclusief de groepsadmins. Laat remove_absent weg of stel het in op false als je alleen personen wilt toevoegen. De oudere waarden 1 en 0 worden ook geaccepteerd.
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"
]
}
Als je hetzelfde verzoek herhaalt, worden geen dubbele lidmaatschappen aangemaakt of uitnodigingen opnieuw verstuurd. Als je een lid met een ingetrokken lidmaatschap opnieuw uitnodigt, krijgt dit lid weer toegang tot de groep, zonder dat een eerdere adminrol wordt hersteld. Nieuwe uitnodigingen en rolwijzigingen gebruiken de normale meldingsprocedure, waarbij geen gebruiker wordt vastgelegd als degene die de actie uitvoert.
Ontbrekende of onjuist opgemaakte e-maillijsten en ongeldige booleaanse waarden leveren HTTP 400 op. Een gedeactiveerd account op de lijst levert HTTP 422 op; reactiveer het expliciet voordat je het toevoegt. Bij ongeldige accountgegevens, abonnementslimieten of andere fouten wordt de volledige synchronisatie teruggedraaid, inclusief nieuwe accounts en ingetrokken lidmaatschappen. Toevoegingen vereisen een actieve groep en blijven onderworpen aan de ledenlimieten van het abonnement.
Lidmaatschapsrollen bijwerken
PATCH /api/server0/memberships/:id
Verstuur een membership-object met een of beide booleaanse velden admin en delegate. Weggelaten rollen blijven ongewijzigd. Onbekende velden worden geweigerd; het endpoint kan geen lidmaatschap overdragen, uitnodiging accepteren of stemgewichten wijzigen.
curl https://loomio.example.org/api/server0/memberships/456 \
-X PATCH \
-H 'Authorization: Bearer YOUR_SERVER_API_KEY' \
--json '{
"membership": {
"admin": true,
"delegate": false
}
}'
Geeft een membership-object terug met dezelfde velden als een opgevraagd lidmaatschap. Het toekennen van een rol maakt de gebruikelijke rolmelding aan; het opnieuw versturen van een ongewijzigde rol leidt niet tot een nieuwe melding. Rolwijzigingen vereisen een actieve groep. Ingetrokken lidmaatschappen leveren HTTP 404 op.
Eén lidmaatschap verwijderen
DELETE /api/server0/memberships/:id
curl https://loomio.example.org/api/server0/memberships/456 \
-X DELETE \
-H 'Authorization: Bearer YOUR_SERVER_API_KEY'
Geeft {"success": true} terug. Verwijdering trekt de toegang tot de groep en de bijbehorende subgroepen in, inclusief toegang tot onderwerpen en stemrechten in actieve peilingen. Het account wordt niet verwijderd, andere groepen worden niet gewijzigd en rechtstreekse toegang tot threads wordt niet ingetrokken. Een herhaalde verwijdering slaagt. Je kunt lidmaatschappen verwijderen uit groepen met verlopen abonnementen; verwijderde groepen leveren HTTP 404 op.
Gebruikersobject
Antwoorden met gebruikersgegevens hebben deze structuur:
{
"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"
}
]
}
Gebruikers opvragen
Vraag alle gebruikersaccounts op de Loomio-installatie op.
GET /api/server0/users
Voorbeeld
curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users
Geeft terug:
{
"users": []
}
Gebruiker tonen
Zoek een gebruiker op basis van het Loomio-gebruikers-ID of de externe identiteit.
GET /api/server0/users/:id
GET /api/server0/users/identity/:identity_type/:uid
Voorbeelden
Op basis van het Loomio-gebruikers-ID:
curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123
Op basis van de externe identiteit:
curl -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123
Geeft terug:
{
"user": {}
}
Gebruiker bijwerken
Werk de profielvelden bij van een gebruiker die je vindt op basis van het Loomio-gebruikers-ID of de externe identiteit.
PATCH /api/server0/users/:id
PATCH /api/server0/users/identity/:identity_type/:uid
Parameters
| Veld | Beschrijving |
|---|---|
name |
Weergavenaam |
username |
Loomio-gebruikersnaam |
email |
E-mailadres |
Voorbeelden
Op basis van het Loomio-gebruikers-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
Op basis van de externe identiteit:
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
Geeft de bijgewerkte gebruiker terug:
{
"user": {}
}
Gebruiker deactiveren
Deactiveer een gebruikersaccount dat je vindt op basis van het Loomio-gebruikers-ID of de externe identiteit.
POST /api/server0/users/:id/deactivate
POST /api/server0/users/identity/:identity_type/:uid/deactivate
Voorbeelden
Op basis van het Loomio-gebruikers-ID:
curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/deactivate
Op basis van de externe identiteit:
curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/deactivate
Geeft terug:
{
"success": true,
"user": {}
}
Gebruiker opnieuw activeren
Activeer een gedeactiveerd gebruikersaccount opnieuw op basis van het Loomio-gebruikers-ID of de externe identiteit.
POST /api/server0/users/:id/reactivate
POST /api/server0/users/identity/:identity_type/:uid/reactivate
Voorbeelden
Op basis van het Loomio-gebruikers-ID:
curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/reactivate
Op basis van de externe identiteit:
curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/reactivate
Retourneert:
{
"success": true,
"user": {}
}
Persoonsgegevens van gebruiker verwijderen
Bij het verwijderen van persoonsgegevens blijven de reacties van de gebruiker en andere door de gebruiker gemaakte inhoud in diens groepen behouden, maar worden bekende persoonlijk identificeerbare gegevens verwijderd, zoals naam, bio, profielfoto, e-mailadres, inloggegevens, identiteiten en actieve sessies.
Dit is de aanbevolen manier om een gebruiker uit Loomio te verwijderen.
POST /api/server0/users/:id/redact
POST /api/server0/users/identity/:identity_type/:uid/redact
Voorbeelden
Op basis van het Loomio-gebruikers-ID:
curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123/redact
Op basis van de externe identiteit:
curl -X POST -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123/redact
Retourneert:
{
"success": true
}
Gebruiker verwijderen
Verwijderen wist de gebruiker en de records die de gebruiker heeft aangemaakt. Reacties worden uit threads verwijderd en stemmen uit peilingen. Ook groepen, discussies, peilingen en andere records die de gebruiker heeft aangemaakt, kunnen via databasekoppelingen worden verwijderd.
Hierdoor gaan veel gegevens verloren. Het wordt sterk aanbevolen om in plaats daarvan de persoonsgegevens te verwijderen.
DELETE /api/server0/users/:id
DELETE /api/server0/users/identity/:identity_type/:uid
Voorbeelden
Op basis van het Loomio-gebruikers-ID:
curl -X DELETE -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/123
Op basis van de externe identiteit:
curl -X DELETE -H 'Authorization: Bearer YOUR_SERVER_API_KEY' https://www.loomio.com/api/server0/users/identity/oauth/external-123
Retourneert:
{
"success": true
}
Instellingen voor SSO-profielsynchronisatie
Gebruik deze instellingen wanneer een ander systeem de profielvelden in Loomio beheert.
LOOMIO_DISABLE_EDIT_USER_PROFILE=1
# LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1
LOOMIO_DISABLE_EDIT_USER_PROFILE=1 voorkomt dat gebruikers deze velden zelf bewerken:
| Veld | Toelichting |
|---|---|
name |
Beheerd via externe synchronisatie |
username |
Beheerd via externe synchronisatie |
email |
Beheerd via externe synchronisatie |
avatar_kind / uploaded_avatar |
Beheerd via externe synchronisatie |
Gebruikers kunnen velden die alleen in Loomio worden gebruikt, zoals short_bio en location, nog steeds bewerken.
LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1 werkt name en email bij op basis van SSO-inloggegevens. Laat deze instelling als commentaar staan of stel deze niet in wanneer alleen een extern synchronisatiescript deze velden moet bijwerken.
LOOMIO_SSO_FORCE_USER_ATTRS werkt nog steeds voor bestaande installaties. Deze instelling voorkomt dat gebruikers de velden bewerken en werkt name en email bij wanneer ze via SSO inloggen.