Документація серверного API Loomio

/api/b3 призначено для операцій на рівні сервера. Для дій від імені користувача Loomio використовуйте /api/b2.

Автентифікація

Задайте для B3_API_KEY секретне значення завдовжки понад 16 символів.

Передавайте ключ як токен Bearer:

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

Передавайте облікові дані лише в заголовку Authorization. API-ключі в рядку запиту або тілі запиту відхиляються.

Об’єкт користувача

Відповіді з даними користувача мають таку структуру:

{
  "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"
    }
  ]
}

Список користувачів

Отримайте список усіх облікових записів користувачів у цьому розгортанні Loomio.

GET /api/b3/users

Приклад

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

Відповідь:

{
  "users": []
}

Перегляд користувача

Знайдіть користувача за його ідентифікатором у Loomio або зовнішнім ідентифікатором.

GET /api/b3/users/:id

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

Приклади

За ідентифікатором користувача в Loomio:

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

За зовнішнім ідентифікатором:

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

Відповідь:

{
  "user": {}
}

Оновлення користувача

Оновіть поля профілю користувача, знайденого за ідентифікатором у Loomio або зовнішнім ідентифікатором.

PATCH /api/b3/users/:id

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

Параметри

Приклади

За ідентифікатором користувача в 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

За зовнішнім ідентифікатором:

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

Відповідь містить оновлені дані користувача:

{
  "user": {}
}

Деактивація користувача

Деактивуйте обліковий запис користувача, знайдений за ідентифікатором у Loomio або зовнішнім ідентифікатором.

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

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

Приклади

За ідентифікатором користувача в Loomio:

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

За зовнішнім ідентифікатором:

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

Відповідь:

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

Повторна активація користувача

Повторно активуйте деактивований обліковий запис користувача, знайдений за ідентифікатором у Loomio або зовнішнім ідентифікатором.

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

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

Приклади

За ідентифікатором користувача в Loomio:

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

За зовнішнім ідентифікатором:

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

Відповідь:

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

Видалення персональних даних користувача

Під час видалення персональних даних коментарі користувача та інший створений ним вміст залишаються в його групах. Водночас видаляються відомі дані, за якими можна встановити особу: ім’я, біографія, фото профілю, адреса електронної пошти, облікові дані для входу, ідентифікатори та активні сеанси.

Це рекомендований спосіб вилучити користувача з Loomio.

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

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

Приклади

За ідентифікатором користувача в Loomio:

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

За зовнішнім ідентифікатором:

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

Відповідь:

{
  "success": true
}

Видалення користувача

Видалення прибирає користувача та створені ним записи. Коментарі видаляються з тем, голоси — з опитувань. Групи, обговорення, опитування та інші створені користувачем записи також можуть бути видалені через зв’язки в базі даних.

Це призводить до значної втрати даних. Натомість наполегливо рекомендуємо знеособити користувача.

DELETE /api/b3/users/:id

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

Приклади

За ідентифікатором користувача в Loomio:

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

За зовнішнім ідентифікатором:

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

Відповідь:

{
  "success": true
}

Налаштування синхронізації профілю через SSO

Використовуйте ці налаштування, якщо полями профілю Loomio керує інша система.

LOOMIO_DISABLE_EDIT_USER_PROFILE=1
# LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1

LOOMIO_DISABLE_EDIT_USER_PROFILE=1 забороняє користувачам самостійно редагувати такі поля:

Користувачі й далі можуть редагувати локальні поля Loomio, як-от short_bio і location.

LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1 оновлює name і email за даними входу через SSO. Якщо ці поля має оновлювати лише зовнішній скрипт синхронізації, залиште цей параметр закоментованим або не задавайте його.

LOOMIO_SSO_FORCE_USER_ATTRS і далі працює в наявних інсталяціях. Він забороняє користувачам редагувати ці поля та оновлює name і email під час входу через SSO.