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

Прагляд уліковага запісу

Знайдзіце ўліковы запіс паводле 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": {}
}

Паўторная актывацыя ўліковага запісу

Паўторна актывуйце дэактываваны ўліковы запіс, знойдзены паводле ідэнтыфікатара ў 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.