Users

Available users 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:

GET /@users HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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:8000/@users/admin",
    "id": "admin",
    "fullname": "Admin",
    "email": "admin@example.com",
    "roles": [
      "Administrator"
    ],
    "groups": []
  },
  {
    "@id": "http://localhost:8000/@users/anonymous",
    "id": "anonymous",
    "fullname": "Anonymous",
    "email": "anonymous@example.com",
    "roles": [
      "Anonymous"
    ],
    "groups": []
  }
]

This only works for Manager users, anonymous users or logged-in users without Manager rights are now allowed to list users. This is the example as an anonymous user:

GET /@users HTTP/1.1
Accept: application/json

The server will return a 401 Unauthorized status code

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "You are not authorization to access this resource."
}

The endpoint supports some basic filtering:

GET /@users?query=admin HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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:8000/@users/admin",
    "id": "admin",
    "fullname": "Admin",
    "email": "admin@example.com",
    "roles": [
      "Administrator"
    ],
    "groups": []
  }
]

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:

POST /@users HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "email": "nearly.headless.nick@example.com",
  "fullname": "Nearly Headless Nick",
  "password": "nearlyheadless",
  "roles": [
      "Contributor"
  ],
  "username": "headlessnick"
}

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

{
  "@id": "http://localhost:8000/@users/headlessnick",
  "id": "headlessnick",
  "fullname": "Nearly Headless Nick",
  "email": "nearly.headless.nick@example.com",
  "roles": [],
  "groups": []
}

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:

GET /@users/admin HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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

GET /@users/admin HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

Only users with Manager rights are allowed to get other users’ information:

GET /@users/admin HTTP/1.1
Accept: application/json

If the user lacks this rights, the server will respond with a 401 Unauthorized status code:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "You are not authorization to access this resource."
}

If the specified user doesn’t exist:

GET /@users/doesnotexist HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

The server will respond with a 404 Not Found status code:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Not found."
}

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:

PATCH /@users/headlessnick HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk
Content-Type: application/json

{
  "fullname": "Headless Nick"
}

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

HTTP/1.1 204 No Content

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:

DELETE /@users/headlessnick HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImZ1bGxuYW1lIjoiQWRtaW4iLCJpYXQiOjE2NDkzMTI0NDl9.RS1Ny_r0v7vIylFfK6q0JVJrkiDuTOh9iG9IL8xbzAk

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

HTTP/1.1 204 No Content

User Registration

If user registration it is enabled, then an anonymous user can register a new user using the user creation endpoint.

To create a new user send a POST request to the @users endpoint:

POST /@users HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "email": "nearly.headless.nick@example.com",
  "fullname": "Nearly Headless Nick",
  "username": "headlessnick",
  "sendPasswordReset": true
}

If the user should receive an email to set her password, you should pass "sendPasswordReset": true in the JSON body of the request. Keep in mind that Plone will send a URL that points to the URL of the Plone site, which might just be your API endpoint.

If the user has been created, the server will respond with a 201 Created response:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "@id": "http://localhost:8000/@users/headlessnick",
  "id": "headlessnick",
  "fullname": "Nearly Headless Nick",
  "email": "nearly.headless.nick@example.com",
  "roles": [],
  "groups": []
}

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 /@users/headlessnick/reset-password HTTP/1.1
Accept: application/json

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

HTTP/1.1 200 OK

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

POST /@users/headlessnick/reset-password HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "reset_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJoZWFkbGVzc25pY2siLCJmdWxsbmFtZSI6Ik5lYXJseSBIZWFkbGVzcyBOaWNrIiwiaWF0IjoxNjQ5Njk4MTUxfQ.K-NLonuCLqcv_hzq4d_vqEVGPLClwpry_HVYRSkJIf4",
  "new_password": "headless"
}

HTTP/1.1 200 OK

Reset Own Password

Users can also reset their 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 /@users/headlessnick/reset-password HTTP/1.1
Accept: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJoZWFkbGVzc25pY2siLCJmdWxsbmFtZSI6Ik5lYXJseSBIZWFkbGVzcyBOaWNrIiwiaWF0IjoxNjQ5Njk4MTUxfQ.K-NLonuCLqcv_hzq4d_vqEVGPLClwpry_HVYRSkJIf4
Content-Type: application/json

{
  "old_password": "nearlyheadless",
  "new_password": "headless"
}

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

HTTP/1.1 200 OK