Documentazione dell'API del server Loomio

/api/b3 serve per le operazioni a livello di server. Usa /api/b2 per le operazioni eseguite tramite un account utente Loomio.

Autenticazione

Imposta B3_API_KEY su un valore segreto di più di 16 caratteri.

Invia la chiave come bearer token:

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

Invia le credenziali solo nell'header Authorization. Le chiavi API nelle stringhe di query o nel corpo delle richieste vengono rifiutate.

Oggetto utente

Le risposte relative agli utenti hanno questa struttura:

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

Elencare gli utenti

Elenca tutti gli account utente dell'installazione Loomio.

GET /api/b3/users

Esempio

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

Restituisce:

{
  "users": []
}

Visualizzare un utente

Trova un utente tramite il suo ID utente Loomio o la sua identità esterna.

GET /api/b3/users/:id

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

Esempi

Tramite ID utente Loomio:

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

Tramite identità esterna:

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

Restituisce:

{
  "user": {}
}

Aggiornare un utente

Aggiorna i campi del profilo di un utente trovato tramite il suo ID utente Loomio o la sua identità esterna.

PATCH /api/b3/users/:id

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

Parametri

Campo	Descrizione
`name`	Nome visualizzato
`username`	Nome utente Loomio
`email`	Indirizzo email

Esempi

Tramite ID utente Loomio:

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/b3/users/123

Tramite identità esterna:

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/b3/users/identity/oauth/external-123

Restituisce l'utente aggiornato:

{
  "user": {}
}

Disattivare un utente

Disattiva un account utente trovato tramite il suo ID utente Loomio o la sua identità esterna.

POST /api/b3/users/:id/deactivate

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

Esempi

Tramite ID utente Loomio:

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

Tramite identità esterna:

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

Restituisce:

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

Riattivare un utente

Riattiva un account utente disattivato trovato tramite il suo ID utente Loomio o la sua identità esterna.

POST /api/b3/users/:id/reactivate

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

Esempi

Tramite ID utente Loomio:

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

Tramite identità esterna:

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

Restituisce:

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

Rimuovere i dati personali di un utente

La rimozione dei dati personali conserva i commenti e gli altri contenuti creati dall'utente nei suoi gruppi, ma elimina le informazioni personali note che possono identificarlo, come nome, biografia, foto del profilo, indirizzo email, credenziali di accesso, identità e sessioni attive.

È il metodo consigliato per rimuovere un utente da Loomio.

POST /api/b3/users/:id/redact

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

Esempi

Tramite ID utente Loomio:

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

Tramite identità esterna:

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

Restituisce:

{
  "success": true
}

Eliminare un utente

L'eliminazione rimuove l'utente e i contenuti che ha creato. I commenti vengono rimossi dalle discussioni e i voti dai sondaggi. Anche i gruppi, le discussioni, i sondaggi e altri contenuti creati dall'utente possono essere eliminati tramite le associazioni del database.

Questa operazione può eliminare molti contenuti. Ti consigliamo di oscurare i dati personali dell'utente.

DELETE /api/b3/users/:id

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

Esempi

Tramite ID utente Loomio:

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

Tramite identità esterna:

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

Restituisce:

{
  "success": true
}

Impostazioni di sincronizzazione del profilo SSO

Usa queste impostazioni quando un altro sistema gestisce i campi del profilo Loomio.

LOOMIO_DISABLE_EDIT_USER_PROFILE=1
# LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1

LOOMIO_DISABLE_EDIT_USER_PROFILE=1 impedisce agli utenti di modificare direttamente questi campi:

Campo	Note
`name`	Gestito dalla sincronizzazione esterna
`username`	Gestito dalla sincronizzazione esterna
`email`	Gestito dalla sincronizzazione esterna
`avatar_kind` / `uploaded_avatar`	Gestito dalla sincronizzazione esterna

Gli utenti possono comunque modificare i campi gestiti in Loomio, come short_bio e location.

LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1 aggiorna name e email con i dati di accesso SSO. Lascialo commentato o non impostato se uno script di sincronizzazione esterno deve essere l'unica fonte di questi aggiornamenti.

LOOMIO_SSO_FORCE_USER_ATTRS funziona ancora nelle installazioni esistenti. Impedisce agli utenti di modificare il profilo e aggiorna name e email all'accesso tramite SSO.