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#

UsersManager.

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#

GroupsManager.

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#

SharingManager.

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.