Users, groups, and sharing#
Manage who can log in, the groups they belong to, and what they can do on each item. For a guide, see Manage users and sharing.
Each example uses the client from How to read these pages.
client.users#
Site users (@users).
client.users.list#
Users of the site.
See list().
Calls GET /@users (plone.restapi documentation).
client.users.list(search="jo")
plone-client users list -q jo -f id,fullname
[
{
"id": "jdoe",
"fullname": "Jo Doe"
}
]
GET /Plone/++api++/@users?search=jo HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/@users?search=jo' -H 'accept: application/json' -u admin:admin
[
{
"fullname": "Jo Doe",
"id": "jdoe"
}
]
This shows only id, fullname of each entry.
client.users.get#
A user.
See get().
Calls GET /@users/jdoe (plone.restapi documentation).
client.users.get("jdoe")
plone-client users get jdoe -f id,email
{
"id": "jdoe",
"email": "jdoe@example.org"
}
GET /Plone/++api++/@users/jdoe HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@users/jdoe -H 'accept: application/json' -u admin:admin
{
"email": "jdoe@example.org",
"fullname": "Jo Doe",
"id": "jdoe",
"roles": [
"Editor",
"Member"
]
}
This shows only id, fullname, email, roles.
client.users.create#
Create a user.
See create().
Calls POST /@users (plone.restapi documentation).
client.users.create(
"asmith",
email="asmith@example.org",
fullname="Ann Smith",
password="correct-horse-battery",
)
echo correct-horse-battery | plone-client users create asmith --email asmith@example.org --fullname "Ann Smith" --password-stdin -f id,fullname
{
"id": "asmith",
"fullname": "Ann Smith"
}
POST /Plone/++api++/@users HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"username": "asmith",
"email": "asmith@example.org",
"fullname": "Ann Smith",
"password": "correct-horse-battery"
}
curl -i -X POST http://localhost:8080/Plone/++api++/@users -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"username":"asmith","email":"asmith@example.org","fullname":"Ann Smith","password":"correct-horse-battery"}'
{
"email": "asmith@example.org",
"fullname": "Ann Smith",
"id": "asmith",
"roles": [
"Member"
]
}
This shows only id, fullname, email, roles.
client.users.update#
Change a user.
See update().
Calls PATCH /@users/jdoe (plone.restapi documentation).
client.users.update("jdoe", fullname="Joanna Doe")
plone-client users update jdoe -s fullname="Joanna Doe"
{
"@id": "http://localhost:8080/Plone/@users/jdoe",
"description": null,
"email": "jdoe@example.org",
"fullname": "Joanna Doe",
"groups": {
"@id": "http://localhost:8080/Plone/++api++/@users/jdoe",
"items": [
{
"id": "AuthenticatedUsers",
"title": "AuthenticatedUsers"
},
{
"id": "editors",
"title": "editors"
}
],
"items_total": 2
},
"home_page": null,
"id": "jdoe",
"location": null,
"portrait": null,
"roles": [
"Editor",
"Member"
],
"username": "jdoe"
}
PATCH /Plone/++api++/@users/jdoe HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"fullname": "Joanna Doe"
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/@users/jdoe -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"fullname":"Joanna Doe"}'
The site answers 204, and the method returns None.
client.users.update_password#
Set a new password.
See update_password().
jdoe_client is a client logged in as jdoe: the site refuses this request from anyone else, a Manager included, and without old_password.
Calls POST /@users/jdoe/reset-password (plone.restapi documentation).
jdoe_client.users.update_password(
"jdoe",
"another-long-password",
old_password="correct-horse-battery",
)
POST /Plone/++api++/@users/jdoe/reset-password HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic amRvZTpjb3JyZWN0LWhvcnNlLWJhdHRlcnk=
{
"new_password": "another-long-password",
"old_password": "correct-horse-battery"
}
curl -i -X POST http://localhost:8080/Plone/++api++/@users/jdoe/reset-password -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"new_password":"another-long-password","old_password":"correct-horse-battery"}'
The site answers 200, and the method returns None.
client.users.reset_password#
Send the user an email to reset the password.
See reset_password().
Calls POST /@users/jdoe/reset-password (plone.restapi documentation).
Note
This example was not run against a site, because the site needs a mail server to send the message. The request below was built, and not sent.
client.users.reset_password("jdoe")
POST /Plone/++api++/@users/jdoe/reset-password HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X POST http://localhost:8080/Plone/++api++/@users/jdoe/reset-password -H 'accept: application/json' -u admin:admin
client.users.delete#
Delete a user.
See delete().
Calls DELETE /@users/todelete (plone.restapi documentation).
client.users.delete("todelete")
plone-client users delete todelete --yes
{
"deleted": "todelete",
"dry_run": false
}
DELETE /Plone/++api++/@users/todelete?delete_memberareas=1&delete_localroles=1 HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X DELETE 'http://localhost:8080/Plone/++api++/@users/todelete?delete_memberareas=1&delete_localroles=1' -H 'accept: application/json' -u admin:admin
The site answers 204, and the method returns None.
client.users.schema#
JSON schema of the user fields (@userschema).
See schema().
Calls GET /@userschema (plone.restapi documentation).
client.users.schema()
GET /Plone/++api++/@userschema HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@userschema -H 'accept: application/json' -u admin:admin
{
"required": [
"email"
],
"type": "object"
}
This shows only required, type.
client.users.portrait#
Portrait image of a user (@portrait).
See portrait().
Calls GET /@portrait/jdoe (plone.restapi documentation).
client.users.portrait("jdoe")
GET /Plone/++api++/@portrait/jdoe HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@portrait/jdoe -H 'accept: application/json' -u admin:admin
The method returns the 42 bytes of the file.
client.groups#
Site groups (@groups).
client.groups.list#
Groups of the site.
See list().
Calls GET /@groups (plone.restapi documentation).
client.groups.list(query="edit")
plone-client groups list -q edit -f id,title
[
{
"id": "editors",
"title": "Editors"
}
]
GET /Plone/++api++/@groups?query=edit HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/@groups?query=edit' -H 'accept: application/json' -u admin:admin
[
{
"id": "editors",
"roles": [
"Editor",
"Authenticated"
],
"title": "Editors"
}
]
This shows only id, title, roles of each entry.
client.groups.get#
A group, with its members.
See get().
Calls GET /@groups/editors (plone.restapi documentation).
client.groups.get("editors")
plone-client groups get editors -f id,title
{
"id": "editors",
"title": "Editors"
}
GET /Plone/++api++/@groups/editors HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@groups/editors -H 'accept: application/json' -u admin:admin
{
"id": "editors",
"members": {
"@id": "http://localhost:8080/Plone/++api++/@groups/editors",
"items": [
"jdoe"
],
"items_total": 1
},
"roles": [
"Editor",
"Authenticated"
],
"title": "Editors"
}
This shows only id, title, roles, members.
client.groups.create#
Create a group.
See create().
Calls POST /@groups (plone.restapi documentation).
client.groups.create("reviewers-team", title="Review team", roles=["Reviewer"])
plone-client groups create reviewers-team --title "Review team" --role Reviewer -f id
{
"id": "reviewers-team"
}
POST /Plone/++api++/@groups HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"groupname": "reviewers-team",
"title": "Review team",
"roles": [
"Reviewer"
]
}
curl -i -X POST http://localhost:8080/Plone/++api++/@groups -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"groupname":"reviewers-team","title":"Review team","roles":["Reviewer"]}'
{
"id": "reviewers-team",
"roles": [
"Reviewer",
"Authenticated"
],
"title": "Review team"
}
This shows only id, title, roles.
client.groups.update#
Change a group.
See update().
Calls PATCH /@groups/editors (plone.restapi documentation).
client.groups.update("editors", description="They edit the news.")
PATCH /Plone/++api++/@groups/editors HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"description": "They edit the news."
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/@groups/editors -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"description":"They edit the news."}'
The site answers 204, and the method returns None.
client.groups.add_members#
Add users to a group.
See add_members().
Calls PATCH /@groups/editors (plone.restapi documentation).
client.groups.add_members("editors", "admin")
plone-client groups add-member editors admin
{
"@id": "http://localhost:8080/Plone/++api++/@groups/editors",
"items": [
"jdoe"
],
"items_total": 1
}
PATCH /Plone/++api++/@groups/editors HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"users": {
"admin": true
}
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/@groups/editors -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"users":{"admin":true}}'
The site answers 204, and the method returns None.
client.groups.remove_members#
Remove users from a group.
See remove_members().
Calls PATCH /@groups/editors (plone.restapi documentation).
client.groups.remove_members("editors", "admin")
plone-client groups remove-member editors admin
{
"@id": "http://localhost:8080/Plone/++api++/@groups/editors",
"items": [
"jdoe"
],
"items_total": 1
}
PATCH /Plone/++api++/@groups/editors HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"users": {
"admin": false
}
}
curl -i -X PATCH http://localhost:8080/Plone/++api++/@groups/editors -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"users":{"admin":false}}'
The site answers 204, and the method returns None.
client.groups.delete#
Delete a group.
See delete().
Calls DELETE /@groups/old-team (plone.restapi documentation).
client.groups.delete("old-team")
plone-client groups delete old-team --yes
{
"deleted": "old-team",
"dry_run": false
}
DELETE /Plone/++api++/@groups/old-team HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X DELETE http://localhost:8080/Plone/++api++/@groups/old-team -H 'accept: application/json' -u admin:admin
The site answers 204, and the method returns None.
client.sharing#
Local roles (@sharing), principals and roles.
client.sharing.get#
Local roles of an item.
See get().
Calls GET /about/@sharing (plone.restapi documentation).
client.sharing.get("/about", search="jdoe")
plone-client sharing /about --search jdoe -f inherit
{
"inherit": true
}
GET /Plone/++api++/about/@sharing?search=jdoe HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/about/@sharing?search=jdoe' -H 'accept: application/json' -u admin:admin
{
"entries": [
{
"id": "AuthenticatedUsers",
"title": "Logged-in users",
"type": "group"
},
{
"id": "jdoe",
"title": "Jo Doe",
"type": "user"
}
],
"inherit": true
}
This shows only inherit, entries. This shows only id, title, type of each entry.
client.sharing.update#
Change local roles of an item.
See update().
Calls POST /about/@sharing (plone.restapi documentation).
client.sharing.update(
"/about",
[{"id": "jdoe", "type": "user", "roles": {"Reader": True}}],
)
POST /Plone/++api++/about/@sharing HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
{
"entries": [
{
"id": "jdoe",
"type": "user",
"roles": {
"Reader": true
}
}
]
}
curl -i -X POST http://localhost:8080/Plone/++api++/about/@sharing -H 'accept: application/json' -H 'content-type: application/json' -u admin:admin --data-raw '{"entries":[{"id":"jdoe","type":"user","roles":{"Reader":true}}]}'
The site answers 204, and the method returns None.
client.sharing.principals#
Users and groups matching a text (@principals).
See principals().
Calls GET /@principals (plone.restapi documentation).
client.sharing.principals("jdoe")
GET /Plone/++api++/@principals?search=jdoe HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET 'http://localhost:8080/Plone/++api++/@principals?search=jdoe' -H 'accept: application/json' -u admin:admin
{
"users": [
{
"fullname": "Jo Doe",
"id": "jdoe"
}
]
}
This shows only users. This shows only id, fullname of each entry.
client.sharing.roles#
Roles defined on the site (@roles).
See roles().
Calls GET /@roles (plone.restapi documentation).
client.sharing.roles()
GET /Plone/++api++/@roles HTTP/1.1
Host: localhost:8080
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
curl -i -X GET http://localhost:8080/Plone/++api++/@roles -H 'accept: application/json' -u admin:admin
[
{
"id": "Contributor",
"title": "Contributor"
},
{
"id": "Editor",
"title": "Editor"
},
{
"id": "Member",
"title": "Member"
}
]
This shows only id, title of each entry. This shows 3 of 7 entries.