Документация по серверному 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": []
}

Получение данных пользователя

Найдите пользователя по его ID в Loomio или внешнему идентификатору.

GET /api/b3/users/:id

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

Примеры

По ID пользователя в 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": {}
}

Обновление данных пользователя

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

PATCH /api/b3/users/:id

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

Параметры

Примеры

По ID пользователя в 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": {}
}

Деактивация пользователя

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

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

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

Примеры

По ID пользователя в 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": {}
}

Повторная активация пользователя

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

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

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

Примеры

По ID пользователя в 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

Примеры

По ID пользователя в 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

Примеры

По ID пользователя в 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.