Документація серверного API Loomio
/api/b3 призначений для операцій на рівні сервера. Використовуйте /api/b2 для дій від імені облікового запису користувача Loomio.
Автентифікація
Задайте для 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
Параметри
| Поле | Опис |
|---|---|
name |
Відображуване ім’я |
username |
Ім’я користувача Loomio |
email |
Адреса електронної пошти |
Приклади
За ідентифікатором користувача 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 забороняє користувачам самостійно редагувати ці поля:
| Поле | Примітки |
|---|---|
name |
Керується зовнішньою синхронізацією |
username |
Керується зовнішньою синхронізацією |
email |
Керується зовнішньою синхронізацією |
avatar_kind / uploaded_avatar |
Керується зовнішньою синхронізацією |
Користувачі й надалі можуть редагувати локальні поля Loomio, як-от short_bio та location.
LOOMIO_SSO_UPDATE_USER_PROFILE_ON_LOGIN=1 оновлює name та email на основі даних входу через SSO. Залиште цей параметр закоментованим або не задавайте його, якщо скрипт зовнішньої синхронізації має бути єдиним джерелом цих оновлень.
LOOMIO_SSO_FORCE_USER_ATTRS і надалі працює в наявних інсталяціях. Він одночасно забороняє користувачам редагувати поля та оновлює name і email під час входу через SSO.