Users

Available users in a Plone site can be created, queried, updated and deleted by interacting with the /@users endpoint on portal root (requires an authenticated user):

List Users

To retrieve a list of all current users in the portal, call the /@users endpoint with a GET request:

http

GET /plone/@users HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@users -H "Accept: application/json" --user admin:secret

httpie

http -j http://nohost/plone/@users -a admin:secret

python-requests

requests.get('http://nohost/plone/@users', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

The server will respond with a list of all users in the portal:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@users/admin", 
    "description": "This is an admin user", 
    "email": "admin@example.com", 
    "fullname": "Administrator", 
    "home_page": "http://www.example.com", 
    "id": "admin", 
    "location": "Berlin", 
    "roles": [
      "Manager"
    ], 
    "username": "admin"
  }, 
  {
    "@id": "http://localhost:55001/plone/@users/test_user_1_", 
    "description": "This is a test user", 
    "email": "test@example.com", 
    "fullname": "Test User", 
    "home_page": "http://www.example.com", 
    "id": "test_user_1_", 
    "location": "Bonn", 
    "roles": [
      "Manager"
    ], 
    "username": "test-user"
  }
]

The endpoint supports some basic filtering:

http

GET /plone/@users?query=noa HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i 'http://nohost/plone/@users?query=noa' -H "Accept: application/json" --user admin:secret

httpie

http -j 'http://nohost/plone/@users?query=noa' -a admin:secret

python-requests

requests.get('http://nohost/plone/@users?query=noa', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

The server will respond with a list the filtered users in the portal with username starts with the query.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "@id": "http://localhost:55001/plone/@users/noam", 
    "description": "Professor of Linguistics", 
    "email": "noam.chomsky@example.com", 
    "fullname": "Noam Avram Chomsky", 
    "home_page": "web.mit.edu/chomsky", 
    "id": "noam", 
    "location": "Cambridge, MA", 
    "roles": [
      "Member"
    ], 
    "username": "noam"
  }
]

The endpoint also takes a limit parameter that defaults to a maximum of 25 users at a time for performance reasons.

Create User

To create a new user, send a POST request to the global /@users endpoint with a JSON representation of the user you want to create in the body:

http

POST /plone/@users HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "description": "Professor of Linguistics",
    "email": "noam.chomsky@example.com",
    "fullname": "Noam Avram Chomsky",
    "home_page": "web.mit.edu/chomsky",
    "location": "Cambridge, MA",
    "password": "colorlessgreenideas",
    "roles": [
        "Contributor"
    ],
    "username": "noamchomsky"
}

curl

curl -i -X POST http://nohost/plone/@users -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"description": "Professor of Linguistics", "email": "noam.chomsky@example.com", "fullname": "Noam Avram Chomsky", "home_page": "web.mit.edu/chomsky", "location": "Cambridge, MA", "password": "colorlessgreenideas", "roles": ["Contributor"], "username": "noamchomsky"}' --user admin:secret

httpie

http -j POST http://nohost/plone/@users description="Professor of Linguistics" email=noam.chomsky@example.com fullname="Noam Avram Chomsky" home_page=web.mit.edu/chomsky location="Cambridge, MA" password=colorlessgreenideas roles:='["Contributor"]' username=noamchomsky -a admin:secret

python-requests

requests.post('http://nohost/plone/@users', headers={'Accept': 'application/json'}, json={'description': 'Professor of Linguistics', 'email': 'noam.chomsky@example.com', 'fullname': 'Noam Avram Chomsky', 'home_page': 'web.mit.edu/chomsky', 'location': 'Cambridge, MA', 'password': 'colorlessgreenideas', 'roles': [u'Contributor'], 'username': 'noamchomsky'}, auth=('admin', 'secret'))

Note

By default, “username”, and “password” are required fields. If email login is enabled, “email” and “password” are required fields. All other fields in the example are optional.

The field “username” is not allowed when email login is enabled.

If the user has been created successfully, the server will respond with a status 201 (Created). The Location header contains the URL of the newly created user and the resource representation in the payload:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://localhost:55001/plone/@users/noamchomsky

{
  "@id": "http://localhost:55001/plone/@users/noamchomsky", 
  "description": "Professor of Linguistics", 
  "email": "noam.chomsky@example.com", 
  "fullname": "Noam Avram Chomsky", 
  "home_page": "web.mit.edu/chomsky", 
  "id": "noamchomsky", 
  "location": "Cambridge, MA", 
  "roles": [
    "Contributor"
  ], 
  "username": "noamchomsky"
}

Read User

To retrieve all details for a particular user, send a GET request to the /@users endpoint and append the user id to the URL:

http

GET /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i http://nohost/plone/@users/noam -H "Accept: application/json" --user admin:secret

httpie

http -j http://nohost/plone/@users/noam -a admin:secret

python-requests

requests.get('http://nohost/plone/@users/noam', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

The server will respond with a 200 OK status code and the JSON representation of the user in the body:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://localhost:55001/plone/@users/noam", 
  "description": "Professor of Linguistics", 
  "email": "noam.chomsky@example.com", 
  "fullname": "Noam Avram Chomsky", 
  "home_page": "web.mit.edu/chomsky", 
  "id": "noam", 
  "location": "Cambridge, MA", 
  "roles": [
    "Member"
  ], 
  "username": "noam"
}

The key ‘roles’ lists the globally defined roles for the user.

Update User

To update the settings of a user, send a PATCH request with the user details you want to amend to the URL of that particular user, e.g. if you want to update the email address of the admin user to:

http

PATCH /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0
Content-Type: application/json

{
    "email": "avram.chomsky@example.com",
    "roles": {
        "Contributor": false
    }
}

curl

curl -i -X PATCH http://nohost/plone/@users/noam -H "Accept: application/json" -H "Content-Type: application/json" --data-raw '{"email": "avram.chomsky@example.com", "roles": {"Contributor": false}}' --user admin:secret

httpie

http -j PATCH http://nohost/plone/@users/noam email=avram.chomsky@example.com roles:='{"Contributor": false}' -a admin:secret

python-requests

requests.patch('http://nohost/plone/@users/noam', headers={'Accept': 'application/json'}, json={'email': 'avram.chomsky@example.com', 'roles': OrderedDict([(u'Contributor', False)])}, auth=('admin', 'secret'))

A successful response to a PATCH request will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

Note

The ‘roles’ object is a mapping of a role and a boolean indicating adding or removing.

Delete User

To delete a user send a DELETE request to the /@users endpoint and append the user id of the user you want to delete, e.g. to delete the user with the id johndoe:

http

DELETE /plone/@users/noam HTTP/1.1
Accept: application/json
Authorization: Basic YWRtaW46c2VjcmV0

curl

curl -i -X DELETE http://nohost/plone/@users/noam -H "Accept: application/json" --user admin:secret

httpie

http -j DELETE http://nohost/plone/@users/noam -a admin:secret

python-requests

requests.delete('http://nohost/plone/@users/noam', headers={'Accept': 'application/json'}, auth=('admin', 'secret'))

A successful response will be indicated by a 204 No Content response:

HTTP/1.1 204 No Content

Reset User Password

Plone allows to reset a password for a user by sending a POST request to the user resource and appending /reset-password to the URL:

POST /plone/@users/noam/reset-password HTTP/1.1
Host: localhost:8080
Accept: application/json

The server will respond with a 200 OK response and send an email to the user to reset her password.

The token that is part of the reset url in the email can be used to authorize setting a new password:

..  http:example:: curl httpie python-requests
request:_json/users_reset.req

Reset Own Password

Plone also allows a user to reset her own password directly without sending an email. The endpoint and the request is the same as above, but now the user can send the old password and the new password as payload:

POST /plone/@users/noam/reset-password HTTP/1.1
Host: localhost:8080
Accept: application/json
Content-Type: application/json

{
  'old_password': 'secret',
  'new_password': 'verysecret',
}

The server will respond with a 200 OK response without sending an email.

To set the password with the old password you need either the Set own password or the plone.app.controlpanel.UsersAndGroups permission.

If an API consumer tries to send a password in the payload that is not the same as the currently logged in user, the server will respond with a 400 Bad Request response.

Return Values