API: Principals

Principals are the superclass of users, groups and placeholder users. This end point returns all principals within a joined collection but can be filtered to e.g. only return groups or users.

Methods

List placehoder users

List all placeholder users. This can only be accessed if the requesting user has the global permission manage_placeholder_user or manage_members in any project.

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • name: filters placeholder users by the name.
  • group: filters placeholder by the group it is contained in.
  • status: filters placeholder by the status it has.

Example:
[{ "name": { "operator": "~", "values": ["Darth"] } }]

select
string

optional query

Comma separated list of properties to include.

Example:
total,elements/name,elements/self,self

200

OK

PrincipalCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self",
            "representations"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This principal collection\n\n**Resource**: Collection"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UserModel"
                  },
                  {
                    "$ref": "#/components/schemas/PlaceholderUserModel"
                  },
                  {
                    "$ref": "#/components/schemas/GroupModel"
                  }
                ]
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_type": "Collection",
    "total": 3,
    "count": 3,
    "_links": {
      "self": {
        "href": "/api/v3/principals"
      }
    },
    "_embedded": {
      "elements": [
        {
          "_hint": "User resource shortened for brevity",
          "_type": "User",
          "id": 1337
        },
        {
          "_hint": "Group resource shortened for brevity",
          "_type": "Group",
          "id": 1338
        },
        {
          "_hint": "PlaceholderUser resource shortened for brevity",
          "_type": "PlaceholderUser",
          "id": 1339
        }
      ]
    }
  }
}

400

Returned if the client sends invalid request parameters e.g. filters

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
  "message": "Filters Invalid filter does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create placeholder user

Creates a new placeholder user. Only administrators and users with manage_placeholder_user global permission are allowed to do so. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

No parameters
null
{
  "name": {
    "type": "string",
    "description": "The new name of the placeholder user to be created."
  }
}

201

Created

PlaceholderUserModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/PrincipalModel"
    },
    {
      "type": "object",
      "required": [
        "_type"
      ],
      "properties": {
        "_type": {
          "type": "string",
          "enum": [
            "PlaceholderUser"
          ]
        },
        "status": {
          "type": "string",
          "description": "The current activation status of the placeholder user.\n\n# Conditions\n\n- User has `manage_placeholder_user` permission globally"
        },
        "_links": {
          "type": "object",
          "required": [
            "showUser"
          ],
          "properties": {
            "showUser": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A relative path to show the placeholder user in the web application."
                }
              ]
            },
            "delete": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "An href to delete the placeholder user.\n\n# Conditions:\n\n- `manage_placeholder_user`"
                }
              ]
            },
            "updateImmediately": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "An href to update the placeholder user.\n\n# Conditions:\n\n- `manage_placeholder_user`\n\n**Resource**: PlaceholderUser"
                }
              ]
            }
          }
        }
      }
    }
  ]
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to create new placeholder users."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)
{
  "_embedded": {
    "details": {
      "attribute": "name"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Name has already been taken."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View placeholder user

Return the placeholder user resource.

id
string

required path

The placeholder user id

Example:
1

200

OK

{
  "_type": "PlaceholderUser",
  "id": 27,
  "name": "Akolyth",
  "createdAt": "2024-02-12T11:52:24.708Z",
  "updatedAt": "2024-02-12T11:52:24.708Z",
  "_links": {
    "self": {
      "href": "/api/v3/placeholder_users/27",
      "title": "Akolyth"
    },
    "memberships": {
      "href": "/api/v3/memberships?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%2227%22%5D%7D%7D%5D",
      "title": "Memberships"
    },
    "updateImmediately": {
      "href": "/api/v3/placeholder_users/27",
      "title": "Update Akolyth",
      "method": "patch"
    },
    "delete": {
      "href": "/api/v3/placeholder_users/27",
      "title": "Delete Akolyth",
      "method": "delete"
    },
    "showUser": {
      "href": "/placeholder_users/27",
      "type": "text/html"
    }
  }
}
PlaceholderUserModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/PrincipalModel"
    },
    {
      "type": "object",
      "required": [
        "_type"
      ],
      "properties": {
        "_type": {
          "type": "string",
          "enum": [
            "PlaceholderUser"
          ]
        },
        "status": {
          "type": "string",
          "description": "The current activation status of the placeholder user.\n\n# Conditions\n\n- User has `manage_placeholder_user` permission globally"
        },
        "_links": {
          "type": "object",
          "required": [
            "showUser"
          ],
          "properties": {
            "showUser": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A relative path to show the placeholder user in the web application."
                }
              ]
            },
            "delete": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "An href to delete the placeholder user.\n\n# Conditions:\n\n- `manage_placeholder_user`"
                }
              ]
            },
            "updateImmediately": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "An href to update the placeholder user.\n\n# Conditions:\n\n- `manage_placeholder_user`\n\n**Resource**: PlaceholderUser"
                }
              ]
            }
          }
        }
      }
    }
  ]
}

404

Returned if the user does not exist or if the API user does not have permission to view them.

Required permission: manage_placeholder_users

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified placeholder user does not exist or you do not have permission to view them."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Update placeholder user

Updates the placeholder user’s writable attributes. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

id
integer

required path

Placeholder user id

Example:
1

null
{
  "name": {
    "type": "string",
    "description": "The new name of the placeholder user to be created."
  }
}

200

OK

PlaceholderUserModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/PrincipalModel"
    },
    {
      "type": "object",
      "required": [
        "_type"
      ],
      "properties": {
        "_type": {
          "type": "string",
          "enum": [
            "PlaceholderUser"
          ]
        },
        "status": {
          "type": "string",
          "description": "The current activation status of the placeholder user.\n\n# Conditions\n\n- User has `manage_placeholder_user` permission globally"
        },
        "_links": {
          "type": "object",
          "required": [
            "showUser"
          ],
          "properties": {
            "showUser": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A relative path to show the placeholder user in the web application."
                }
              ]
            },
            "delete": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "An href to delete the placeholder user.\n\n# Conditions:\n\n- `manage_placeholder_user`"
                }
              ]
            },
            "updateImmediately": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "An href to update the placeholder user.\n\n# Conditions:\n\n- `manage_placeholder_user`\n\n**Resource**: PlaceholderUser"
                }
              ]
            }
          }
        }
      }
    }
  ]
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage_placeholder_users

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to update the account of this user."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the placeholder user does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified placeholder user does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)
  • a constraint for a property was violated (PropertyConstraintViolation)
{
  "_embedded": {
    "details": {
      "attribute": "name"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Name has already been taken."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Delete placeholder user

Set the specified placeholder user to deleted status.

id
integer

required path

Placeholder user id

Example:
1

202

Returned if the group was marked for deletion.

Note that the response body is empty as of now. In future versions of the API a body might be returned, indicating the progress of deletion.

403

Returned if the client does not have sufficient permissions.

Required permission: manage_placeholder_users

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete the account of this user."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the placeholder user does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified placeholder user does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List principals

List all principals. The client can choose to filter the principals similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain principals who are members in projects the client is allowed to see.

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • type: filters principals by their type (User, Group, PlaceholderUser).
  • member: filters principals by the projects they are members in.
  • name: filters principals by the user or group name.
  • any_name_attribute: filters principals by the user or group first- and last name, email or login.
  • status: filters principals by their status number (active = 1, registered = 2, locked = 3, invited = 4)

Example:
[{ "type": { "operator": "=", "values": ["User"] } }]

select
string

optional query

Comma separated list of properties to include.

Example:
total,elements/name,elements/self,self

200

OK

PrincipalCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self",
            "representations"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This principal collection\n\n**Resource**: Collection"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/UserModel"
                  },
                  {
                    "$ref": "#/components/schemas/PlaceholderUserModel"
                  },
                  {
                    "$ref": "#/components/schemas/GroupModel"
                  }
                ]
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_type": "Collection",
    "total": 3,
    "count": 3,
    "_links": {
      "self": {
        "href": "/api/v3/principals"
      }
    },
    "_embedded": {
      "elements": [
        {
          "_hint": "User resource shortened for brevity",
          "_type": "User",
          "id": 1337
        },
        {
          "_hint": "Group resource shortened for brevity",
          "_type": "Group",
          "id": 1338
        },
        {
          "_hint": "PlaceholderUser resource shortened for brevity",
          "_type": "PlaceholderUser",
          "id": 1339
        }
      ]
    }
  }
}

400

Returned if the client sends invalid request parameters e.g. filters

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidQuery",
  "message": "Filters Invalid filter does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List users

Lists users. Only administrators or users with any of the following can access this resource:

  • manage_members
  • manage_user
  • share_work_packages

offset
integer

optional query

Page number inside the requested collection.

Default:
1

Example:
25

pageSize
integer

optional query

Number of elements to display per page.

Example:
25

filters
string

optional query

JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:

  • status: Status the user has

  • group: Name of the group in which to-be-listed users are members.

  • name: Filter users in whose first or last names, or email addresses the given string occurs.

  • login: User’s login

Example:
[{ "status": { "operator": "=", "values": ["invited"] } }, { "group": { "operator": "=", "values": ["1"] } }, { "name": { "operator": "=", "values": ["h.wurst@openproject.com"] } }]

sortBy
string

optional query

JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint.

Example:
[["status", "asc"]]

select
string

optional query

Comma separated list of properties to include.

Example:
total,elements/name,elements/self,self

200

OK

UserCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This user collection\n\n**Resource**: Collection"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/UserModel"
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_links": {
      "self": {
        "href": "/api/v3/users"
      }
    },
    "_embedded": {
      "elements": [
        {
          "_hint": "User resource shortened for brevity",
          "_type": "User",
          "id": 1337
        },
        {
          "_hint": "User resource shortened for brevity",
          "_type": "User",
          "id": 1338
        }
      ]
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator or any of: ‘manage_members’, ‘manage_user’, ‘share_work_packages’.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to list users."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create user

Creates a new user. Only administrators and users with manage_user global permission are allowed to do so. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

Valid values for status:

  1. “active” - In this case a password has to be provided in addition to the other attributes.

  2. “invited” - In this case nothing but the email address is required. The rest is optional. An invitation will be sent to the user.

No parameters
{
  "login": "j.sheppard",
  "password": "idestroyedsouvereign",
  "firstName": "John",
  "lastName": "Sheppard",
  "email": "shep@mail.com",
  "admin": true,
  "status": "active",
  "language": "en"
}
{
  "admin": {
    "type": "boolean"
  },
  "email": {
    "type": "string",
    "maxLength": 60
  },
  "login": {
    "type": "string",
    "maxLength": 256
  },
  "password": {
    "type": "string",
    "description": "The users password.\n\n*Conditions:*\n\nOnly writable on creation, not on update."
  },
  "firstName": {
    "type": "string",
    "maxLength": 30
  },
  "lastName": {
    "type": "string",
    "maxLength": 30
  },
  "status": {
    "type": "string",
    "description": "The current activation status of the user.\n\n*Conditions:*\n\nOnly writable on creation, not on update."
  },
  "language": {
    "type": "string"
  }
}

201

Created

UserModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/PrincipalModel"
    },
    {
      "type": "object",
      "required": [
        "_type",
        "avatar"
      ],
      "properties": {
        "_type": {
          "type": "string",
          "enum": [
            "User"
          ]
        },
        "avatar": {
          "type": "string",
          "format": "uri",
          "description": "URL to user's avatar"
        },
        "login": {
          "type": "string",
          "description": "The user's login name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 256
        },
        "firstName": {
          "type": "string",
          "description": "The user's first name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 30
        },
        "lastName": {
          "type": "string",
          "description": "The user's last name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 30
        },
        "email": {
          "type": "string",
          "description": "The user's email address\n\n# Conditions\n\n- E-Mail address not hidden\n- User is not a new record\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 60
        },
        "admin": {
          "type": "boolean",
          "description": "Flag indicating whether or not the user is an admin\n\n# Conditions\n\n- `admin`"
        },
        "status": {
          "type": "string",
          "description": "The current activation status of the user.\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "language": {
          "type": "string",
          "description": "User's language | ISO 639-1 format\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "identityUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "User's identity_url for OmniAuth authentication.\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "Time of creation"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Time of the most recent change to the user"
        },
        "_links": {
          "type": "object",
          "properties": {
            "showUser": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A relative path to show the user in the web application.\n\n# Condition\n\n- User is not a new record\n- User is not `locked`"
                }
              ]
            },
            "updateImmediately": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A link to update the user resource.\n\n# Conditions\n\n- `admin`"
                }
              ]
            },
            "lock": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Restrict the user from logging in and performing any actions.\n\n# Conditions\n\n- User is not locked\n- `admin`"
                }
              ]
            },
            "unlock": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Allow a locked user to login and act again.\n\n# Conditions\n\n- User is not locked\n- `admin`"
                }
              ]
            },
            "delete": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Permanently remove a user from the instance\n\n# Conditions\n\neither:\n  - `admin`\n  - Setting `users_deletable_by_admin` is set\nor:\n  - User is self\n  - Setting `users_deletable_by_self` is set"
                }
              ]
            },
            "authSource": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Permanently remove a user from the instance\n\n# Conditions\n\n- LDAP authentication configured\n- `admin`"
                }
              ]
            }
          }
        }
      }
    }
  ]
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrator

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to create new users."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • a constraint for a property was violated (PropertyConstraintViolation)
{
  "_embedded": {
    "details": {
      "attribute": "email"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "The email address is already taken."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View user

id
string

required path

User id. Use me to reference current user, if any.

Example:
1

200

OK

{
  "_type": "User",
  "id": 14,
  "name": "Mara Jade",
  "createdAt": "2022-04-04T08:07:22.910Z",
  "updatedAt": "2024-02-09T09:01:17.382Z",
  "login": "member",
  "admin": false,
  "firstName": "Mara",
  "lastName": "Jade",
  "email": "m.jade@empire.org",
  "avatar": "https://secure.gravatar.com/avatar/17dd23570f3bd129d06db9b48b7a41b8?default=404&secure=true",
  "status": "active",
  "identityUrl": null,
  "language": "en",
  "_links": {
    "self": {
      "href": "/api/v3/users/14",
      "title": "Mara Jade"
    },
    "memberships": {
      "href": "/api/v3/memberships?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%2214%22%5D%7D%7D%5D",
      "title": "Memberships"
    },
    "showUser": {
      "href": "/users/14",
      "type": "text/html"
    },
    "updateImmediately": {
      "href": "/api/v3/users/14",
      "title": "Update member",
      "method": "patch"
    },
    "lock": {
      "href": "/api/v3/users/14/lock",
      "title": "Set lock on member",
      "method": "post"
    },
    "delete": {
      "href": "/api/v3/users/14",
      "title": "Delete member",
      "method": "delete"
    }
  }
}
UserModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/PrincipalModel"
    },
    {
      "type": "object",
      "required": [
        "_type",
        "avatar"
      ],
      "properties": {
        "_type": {
          "type": "string",
          "enum": [
            "User"
          ]
        },
        "avatar": {
          "type": "string",
          "format": "uri",
          "description": "URL to user's avatar"
        },
        "login": {
          "type": "string",
          "description": "The user's login name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 256
        },
        "firstName": {
          "type": "string",
          "description": "The user's first name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 30
        },
        "lastName": {
          "type": "string",
          "description": "The user's last name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 30
        },
        "email": {
          "type": "string",
          "description": "The user's email address\n\n# Conditions\n\n- E-Mail address not hidden\n- User is not a new record\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 60
        },
        "admin": {
          "type": "boolean",
          "description": "Flag indicating whether or not the user is an admin\n\n# Conditions\n\n- `admin`"
        },
        "status": {
          "type": "string",
          "description": "The current activation status of the user.\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "language": {
          "type": "string",
          "description": "User's language | ISO 639-1 format\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "identityUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "User's identity_url for OmniAuth authentication.\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "Time of creation"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Time of the most recent change to the user"
        },
        "_links": {
          "type": "object",
          "properties": {
            "showUser": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A relative path to show the user in the web application.\n\n# Condition\n\n- User is not a new record\n- User is not `locked`"
                }
              ]
            },
            "updateImmediately": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A link to update the user resource.\n\n# Conditions\n\n- `admin`"
                }
              ]
            },
            "lock": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Restrict the user from logging in and performing any actions.\n\n# Conditions\n\n- User is not locked\n- `admin`"
                }
              ]
            },
            "unlock": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Allow a locked user to login and act again.\n\n# Conditions\n\n- User is not locked\n- `admin`"
                }
              ]
            },
            "delete": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Permanently remove a user from the instance\n\n# Conditions\n\neither:\n  - `admin`\n  - Setting `users_deletable_by_admin` is set\nor:\n  - User is self\n  - Setting `users_deletable_by_self` is set"
                }
              ]
            },
            "authSource": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Permanently remove a user from the instance\n\n# Conditions\n\n- LDAP authentication configured\n- `admin`"
                }
              ]
            }
          }
        }
      }
    }
  ]
}

404

Returned if the user does not exist or if the API user does not have permission to view them.

Required permission The user needs to be locked in if the installation is configured to prevent anonymous access

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist or you do not have permission to view them."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Update user

Updates the user’s writable attributes. When calling this endpoint the client provides a single object, containing at least the properties and links that are required, in the body.

id
integer

required path

User id

Example:
1

{
  "login": "j.sheppard",
  "password": "idestroyedsouvereign",
  "firstName": "John",
  "lastName": "Sheppard",
  "email": "shep@mail.com",
  "admin": true,
  "status": "active",
  "language": "en"
}
{
  "admin": {
    "type": "boolean"
  },
  "email": {
    "type": "string",
    "maxLength": 60
  },
  "login": {
    "type": "string",
    "maxLength": 256
  },
  "password": {
    "type": "string",
    "description": "The users password.\n\n*Conditions:*\n\nOnly writable on creation, not on update."
  },
  "firstName": {
    "type": "string",
    "maxLength": 30
  },
  "lastName": {
    "type": "string",
    "maxLength": 30
  },
  "status": {
    "type": "string",
    "description": "The current activation status of the user.\n\n*Conditions:*\n\nOnly writable on creation, not on update."
  },
  "language": {
    "type": "string"
  }
}

200

OK

UserModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/PrincipalModel"
    },
    {
      "type": "object",
      "required": [
        "_type",
        "avatar"
      ],
      "properties": {
        "_type": {
          "type": "string",
          "enum": [
            "User"
          ]
        },
        "avatar": {
          "type": "string",
          "format": "uri",
          "description": "URL to user's avatar"
        },
        "login": {
          "type": "string",
          "description": "The user's login name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 256
        },
        "firstName": {
          "type": "string",
          "description": "The user's first name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 30
        },
        "lastName": {
          "type": "string",
          "description": "The user's last name\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 30
        },
        "email": {
          "type": "string",
          "description": "The user's email address\n\n# Conditions\n\n- E-Mail address not hidden\n- User is not a new record\n- User is self, or `create_user` or `manage_user` permission globally",
          "maxLength": 60
        },
        "admin": {
          "type": "boolean",
          "description": "Flag indicating whether or not the user is an admin\n\n# Conditions\n\n- `admin`"
        },
        "status": {
          "type": "string",
          "description": "The current activation status of the user.\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "language": {
          "type": "string",
          "description": "User's language | ISO 639-1 format\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "identityUrl": {
          "type": [
            "string",
            "null"
          ],
          "description": "User's identity_url for OmniAuth authentication.\n\n# Conditions\n\n- User is self, or `create_user` or `manage_user` permission globally"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "Time of creation"
        },
        "updatedAt": {
          "type": "string",
          "format": "date-time",
          "description": "Time of the most recent change to the user"
        },
        "_links": {
          "type": "object",
          "properties": {
            "showUser": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A relative path to show the user in the web application.\n\n# Condition\n\n- User is not a new record\n- User is not `locked`"
                }
              ]
            },
            "updateImmediately": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "A link to update the user resource.\n\n# Conditions\n\n- `admin`"
                }
              ]
            },
            "lock": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Restrict the user from logging in and performing any actions.\n\n# Conditions\n\n- User is not locked\n- `admin`"
                }
              ]
            },
            "unlock": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Allow a locked user to login and act again.\n\n# Conditions\n\n- User is not locked\n- `admin`"
                }
              ]
            },
            "delete": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Permanently remove a user from the instance\n\n# Conditions\n\neither:\n  - `admin`\n  - Setting `users_deletable_by_admin` is set\nor:\n  - User is self\n  - Setting `users_deletable_by_self` is set"
                }
              ]
            },
            "authSource": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "Permanently remove a user from the instance\n\n# Conditions\n\n- LDAP authentication configured\n- `admin`"
                }
              ]
            }
          }
        }
      }
    }
  ]
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: Administrators, manage_user global permission

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to update the account of this user."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user does not exist or if the API user does not have the necessary permissions to update it.

Required permission: Administrators only (exception: users may update their own accounts)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist or you do not have permission to view them."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"
{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if:

  • the client tries to modify a read-only property (PropertyIsReadOnly)

  • a constraint for a property was violated (PropertyConstraintViolation)

{
  "_embedded": {
    "details": {
      "attribute": "email"
    }
  },
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "The email address is already taken."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Delete user

Permanently deletes the specified user account.

id
integer

required path

User id

Example:
1

202

Returned if the account was deleted successfully.

Note that the response body is empty as of now. In future versions of the API a body might be returned, indicating the progress of deletion.

403

Returned if the client does not have sufficient permissions or if deletion of users was disabled in the instance wide settings.

Required permission: Administrators only (exception: users might be able to delete their own accounts)

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not allowed to delete the account of this user."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user does not exist.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}