תיעוד 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.