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.

Deze pagina is automatisch vertaald. Als een woord niet klopt of onduidelijk is, stuur dan een e-mail naar contact@loomio.org en we passen het aan.