API: Memberships
Users and groups can become members of a project. Such a membership will also have one or more roles assigned to it. By that, memberships control the permissions a user has within a project.
There are also memberships that do not govern the permissions within a certain project but rather govern global permissions. Among the permissions that can be granted like this are the permissions to “Create project” and “Manage users”. Those memberships do not have a project associated.
When creating and updating memberships, a custom message can be sent to users of new and updated memberships. This message can be provided within the _meta group.
Linked Properties
| Link | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| self | This membership | Membership | not null | READ |
| project | The project for which the membership is granted | Project | READ | |
| roles | The list of roles the user or group is granted in the project | RoleCollection | not null | READ |
| principal | The user or group that was granted membership | User or Group | not null | READ |
Local Properties
| Property | Description | Type | Constraints | Supported operations |
|---|---|---|---|---|
| id | Membership id | Integer | x > 0 | READ |
| createdAt | Time of creation | DateTime | not null | READ |
| updatedAt | Time of latest update | DateTime | not null | READ |
Meta parameters
| Meta property | Description | Type | Constraints | Supported operations | Condition |
|---|---|---|---|---|---|
| notificationMessage | The message included in the email(s) send to the users of new or updated memberships | Formattable | READ/WRITE |
Methods
List memberships
get /api/v3/membershipsReturns a collection of memberships. The client can choose to filter the memberships similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain memberships, for which the requesting client has sufficient permissions (view_members, manage_members).
filters
string
optional query
JSON specifying filter conditions. Accepts the same format as returned by the queries endpoint. Currently supported filters are:
-
any_name_attribute: filters memberships based on the name of the principal. All possible name variants (and also email and login) are searched.
-
blocked: reduces the result set to all memberships that are temporarily blocked or that are not blocked temporarily.
-
group: filters memberships based on the name of a group. The group however is not the principal used for filtering. Rather, the memberships of the group are used as the filter values.
-
name: filters memberships based on the name of the principal. Note that only the name is used which depends on a setting in the OpenProject instance.
-
principal: filters memberships based on the id of the principal.
-
project: filters memberships based on the id of the project.
-
role: filters memberships based on the id of any role assigned to the membership.
-
status: filters memberships based on the status of the principal.
-
created_at: filters memberships based on the time the membership was created.
-
updated_at: filters memberships based on the time the membership was updated last.
sortBy
string
optional query
JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:
-
id: Sort by primary key
-
name: Sort by the name of the principal. Note that this depends on the setting for how the name is to be displayed at least for users.
-
email: Sort by the email address of the principal. Groups and principal users, which do not have an email, are sorted last.
-
status: Sort by the status of the principal. Groups and principal users, which do not have a status, are sorted together with the active users.
-
created_at: Sort by membership creation datetime
-
updated_at: Sort by the time the membership was updated last
Default:[["id", "asc"]]
Example:[["id", "asc"]]
200
OK
application/hal+json {
"_embedded": {
"elements": [
{
"_links": {
"principal": {
"href": "/api/v3/users/5",
"title": "A user"
},
"project": {
"href": "/api/v3/projects/3",
"title": "A Project"
},
"roles": [
{
"href": "/api/v3/roles/4",
"title": "Reader"
}
],
"schema": {
"href": "/api/v3/memberships/schema"
},
"self": {
"href": "/api/v3/memberships/11"
}
},
"_type": "Membership",
"createdAt": "2015-03-20T12:56:56Z",
"id": 11,
"updatedAt": "2018-12-20T18:16:11Z"
},
{
"_links": {
"principal": {
"href": "/api/v3/groups/5",
"title": "A group"
},
"project": {
"href": "/api/v3/projects/6",
"title": "Another Project"
},
"roles": [
{
"href": "/api/v3/roles/8",
"title": "Project admin"
}
],
"schema": {
"href": "/api/v3/memberships/schema"
},
"self": {
"href": "/api/v3/memberships/41"
}
},
"_type": "Membership",
"createdAt": "2019-12-22T12:56:06Z",
"id": 41,
"updatedAt": "2020-12-20T18:16:12Z"
}
]
},
"_links": {
"self": {
"href": "/api/v3/memberships"
}
},
"_type": "Collection",
"count": 2,
"total": 2
}
List_membershipsModel {
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/memberships"
}
},
"total": 2,
"count": 2,
"_type": "Collection",
"_embedded": {
"elements": [
{
"_links": {
"self": {
"href": "/api/v3/memberships/11"
},
"schema": {
"href": "/api/v3/memberships/schema"
},
"project": {
"href": "/api/v3/projects/3",
"title": "A Project"
},
"principal": {
"href": "/api/v3/users/5",
"title": "A user"
},
"roles": [
{
"href": "/api/v3/roles/4",
"title": "Reader"
}
]
},
"_type": "Membership",
"id": 11,
"createdAt": "2015-03-20T12:56:56Z",
"updatedAt": "2018-12-20T18:16:11Z"
},
{
"_links": {
"self": {
"href": "/api/v3/memberships/41"
},
"schema": {
"href": "/api/v3/memberships/schema"
},
"project": {
"href": "/api/v3/projects/6",
"title": "Another Project"
},
"principal": {
"href": "/api/v3/groups/5",
"title": "A group"
},
"roles": [
{
"href": "/api/v3/roles/8",
"title": "Project admin"
}
]
},
"_type": "Membership",
"id": 41,
"createdAt": "2019-12-22T12:56:06Z",
"updatedAt": "2020-12-20T18:16:12Z"
}
]
}
}
}
Create membership
post /api/v3/membershipsCreates a new membership applying the attributes provided in the body.
You can use the form and schema to retrieve the valid attribute values and by that be guided towards successful creation.
By providing a notificationMessage within the _meta block of the payload, the client can include a customized message to the user of the newly created membership. In case of a group, the message will be sent to every user belonging to the group.
By including { "sendNotifications": false } within the _meta block of the payload, no notifications is send out at all.
201
Created
application/hal+json View_membershipModel {
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/memberships/11",
"title": "Some user"
},
"schema": {
"href": "/api/v3/memberships/schema"
},
"update": {
"href": "/api/v3/memberships/11/form",
"method": "post"
},
"updateImmediately": {
"href": "/api/v3/memberships/11",
"method": "patch"
},
"project": {
"href": "/api/v3/projects/3",
"title": "A project"
},
"principal": {
"href": "/api/v3/users/4",
"title": "Some user"
},
"roles": [
{
"href": "/api/v3/roles/5",
"title": "Member"
},
{
"href": "/api/v3/roles/4",
"title": "Reader"
}
]
},
"_type": "Membership",
"id": 11,
"createdAt": "2015-03-20T12:56:56Z",
"updatedAt": "2018-12-20T18:16:11Z",
"_embedded": {
"project...": {
},
"principal...": {
},
"roles...": [
]
}
}
}
400
403
Returned if the client does not have sufficient permissions.
Required permission: Manage members
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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
415
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
application/hal+json {
"_embedded": {
"details": {
"attribute": "project"
}
},
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Project can't be blank."
}
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."
}
}
}
Available projects for memberships
get /api/v3/memberships/available_projectsGets a list of projects in which a membership can be created in. The list contains all projects in which the user issuing the request has the manage members permissions.
200
OK
application/hal+json {
"_embedded": {
"elements": [
{
"_links": {
"categories": {
"href": "/api/v3/projects/6/categories"
},
"createWorkPackage": {
"href": "/api/v3/projects/6/work_packages/form",
"method": "post"
},
"createWorkPackageImmediate": {
"href": "/api/v3/projects/6/work_packages",
"method": "post"
},
"editWorkPackage": {
"href": "/api/v3//work_packages/{id}/form",
"method": "post",
"templated": true
},
"memberships": {
"href": "/api/v3/projects/6/memberships"
},
"self": {
"href": "/api/v3/projects/6",
"title": "A project"
}
},
"_type": "Project",
"createdAt": "2015-07-06T13:28:14+00:00",
"description": "Eveniet molestias omnis quis aut qui eum adipisci. Atque aut aut in exercitationem adipisci amet. Nisi asperiores quia ratione veritatis enim exercitationem magnam. Aut fuga architecto adipisci nihil. Et repellat pariatur. Aliquam et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.",
"id": 6,
"identifier": "a_project",
"name": "A project",
"type": "Customer Project",
"updatedAt": "2015-10-01T09:55:02+00:00"
},
{
"_links": {
"categories": {
"href": "/api/v3/projects/14/categories"
},
"createWorkPackage": {
"href": "/api/v3/projects/14/work_packages/form",
"method": "post"
},
"createWorkPackageImmediate": {
"href": "/api/v3/projects/14/work_packages",
"method": "post"
},
"memberships": {
"href": "/api/v3/projects/14/memberships"
},
"self": {
"href": "/api/v3/projects/14",
"title": "Another project"
}
},
"_type": "Project",
"createdAt": "2016-02-29T12:50:20+00:00",
"description": "",
"id": 14,
"identifier": "another_project",
"name": "Another project",
"type": null,
"updatedAt": "2016-02-29T12:50:20+00:00"
}
]
},
"_links": {
"self": {
"href": "/api/v3/memberships/available_projects"
}
},
"_type": "Collection",
"count": 2,
"total": 2
}
Available_projects_for_membershipsModel {
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/memberships/available_projects"
}
},
"_type": "Collection",
"total": 2,
"count": 2,
"_embedded": {
"elements": [
{
"_type": "Project",
"_links": {
"self": {
"href": "/api/v3/projects/6",
"title": "A project"
},
"editWorkPackage": {
"href": "/api/v3/work_packages/{id}/form",
"templated": true,
"method": "post"
},
"createWorkPackage": {
"href": "/api/v3/projects/6/work_packages/form",
"method": "post"
},
"createWorkPackageImmediate": {
"href": "/api/v3/projects/6/work_packages",
"method": "post"
},
"categories": {
"href": "/api/v3/projects/6/categories"
},
"memberships": {
"href": "/api/v3/projects/6/memberships"
}
},
"id": 6,
"identifier": "a_project",
"name": "A project",
"description": "Eveniet molestias omnis quis aut qui eum adipisci. Atque aut aut in exercitationem adipisci amet. Nisi asperiores quia ratione veritatis enim exercitationem magnam. Aut fuga architecto adipisci nihil. Et repellat pariatur. Aliquam et sed perferendis nostrum quaerat. Fugit doloremque voluptatem.",
"createdAt": "2015-07-06T13:28:14+00:00",
"updatedAt": "2015-10-01T09:55:02+00:00",
"type": "Customer Project"
},
{
"_type": "Project",
"_links": {
"self": {
"href": "/api/v3/projects/14",
"title": "Another project"
},
"createWorkPackage": {
"href": "/api/v3/projects/14/work_packages/form",
"method": "post"
},
"createWorkPackageImmediate": {
"href": "/api/v3/projects/14/work_packages",
"method": "post"
},
"categories": {
"href": "/api/v3/projects/14/categories"
},
"memberships": {
"href": "/api/v3/projects/14/memberships"
}
},
"id": 14,
"identifier": "another_project",
"name": "Another project",
"description": "",
"createdAt": "2016-02-29T12:50:20+00:00",
"updatedAt": "2016-02-29T12:50:20+00:00",
"type": null
}
]
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: manage members
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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."
}
}
}
Membership create form
post /api/v3/memberships/form200
OK
400
403
Returned if the client does not have sufficient permissions.
Required permission: manage memberships in any project
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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
415
View membership schema
get /api/v3/memberships/schema200
OK
application/hal+json {
"_dependencies": [
],
"_links": {
"self": {
"href": "/api/v3/memberships/schema"
}
},
"_type": "Schema",
"createdAt": {
"hasDefault": false,
"name": "Created on",
"required": true,
"type": "DateTime",
"writable": false
},
"id": {
"hasDefault": false,
"name": "ID",
"required": true,
"type": "Integer",
"writable": false
},
"notificationMessage": {
"hasDefault": false,
"location": "_meta",
"name": "Message",
"options": {
},
"required": false,
"type": "Formattable",
"writable": true
},
"principal": {
"_links": {
},
"hasDefault": false,
"location": "_links",
"name": "Principal",
"required": true,
"type": "Principal",
"writable": true
},
"project": {
"_links": {
},
"hasDefault": false,
"location": "_links",
"name": "Project",
"required": false,
"type": "Project",
"writable": true
},
"roles": {
"_links": {
},
"hasDefault": false,
"location": "_links",
"name": "Role",
"required": true,
"type": "[]Role",
"writable": true
},
"updatedAt": {
"hasDefault": false,
"name": "Updated on",
"required": true,
"type": "DateTime",
"writable": false
}
}
View_membership_schemaModel {
"type": "object",
"example": {
"_type": "Schema",
"_dependencies": [
],
"id": {
"type": "Integer",
"name": "ID",
"required": true,
"hasDefault": false,
"writable": false
},
"createdAt": {
"type": "DateTime",
"name": "Created on",
"required": true,
"hasDefault": false,
"writable": false
},
"updatedAt": {
"type": "DateTime",
"name": "Updated on",
"required": true,
"hasDefault": false,
"writable": false
},
"notificationMessage": {
"type": "Formattable",
"name": "Message",
"required": false,
"hasDefault": false,
"writable": true,
"options": {
},
"location": "_meta"
},
"project": {
"type": "Project",
"name": "Project",
"required": false,
"hasDefault": false,
"writable": true,
"location": "_links",
"_links": {
}
},
"principal": {
"type": "Principal",
"name": "Principal",
"required": true,
"hasDefault": false,
"writable": true,
"location": "_links",
"_links": {
}
},
"roles": {
"type": "[]Role",
"name": "Role",
"required": true,
"hasDefault": false,
"writable": true,
"location": "_links",
"_links": {
}
},
"_links": {
"self": {
"href": "/api/v3/memberships/schema"
}
}
}
}
403
Returned if the client does not have sufficient permissions to see the schema.
Required permission: manage members or view memberships on any project
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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 membership
get /api/v3/memberships/{id} id
integer
required path
Membership id
Example:1
200
OK
application/hal+json {
"_embedded": {
"principal...": {
},
"project...": {
},
"roles...": [
]
},
"_links": {
"principal": {
"href": "/api/v3/users/4",
"title": "Some user"
},
"project": {
"href": "/api/v3/projects/3",
"title": "A project"
},
"roles": [
{
"href": "/api/v3/roles/5",
"title": "Member"
},
{
"href": "/api/v3/roles/4",
"title": "Reader"
}
],
"schema": {
"href": "/api/v3/memberships/schema"
},
"self": {
"href": "/api/v3/memberships/11",
"title": "Some user"
},
"update": {
"href": "/api/v3/memberships/11/form",
"method": "post"
},
"updateImmediately": {
"href": "/api/v3/memberships/11",
"method": "patch"
}
},
"_type": "Membership",
"createdAt": "2015-03-20T12:56:56Z",
"id": 11,
"updatedAt": "2018-12-20T18:16:11Z"
}
View_membershipModel {
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/memberships/11",
"title": "Some user"
},
"schema": {
"href": "/api/v3/memberships/schema"
},
"update": {
"href": "/api/v3/memberships/11/form",
"method": "post"
},
"updateImmediately": {
"href": "/api/v3/memberships/11",
"method": "patch"
},
"project": {
"href": "/api/v3/projects/3",
"title": "A project"
},
"principal": {
"href": "/api/v3/users/4",
"title": "Some user"
},
"roles": [
{
"href": "/api/v3/roles/5",
"title": "Member"
},
{
"href": "/api/v3/roles/4",
"title": "Reader"
}
]
},
"_type": "Membership",
"id": 11,
"createdAt": "2015-03-20T12:56:56Z",
"updatedAt": "2018-12-20T18:16:11Z",
"_embedded": {
"project...": {
},
"principal...": {
},
"roles...": [
]
}
}
}
404
Returned if the membership does not exist or the client does not have sufficient permissions to see it.
Required permission: view members or manage members
Note: A client without sufficient permissions shall not be able to test for the existence of a membership. That’s why a 404 is returned here, even if a 403 might be more appropriate.
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
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 membership
patch /api/v3/memberships/{id}Updates the given membership by applying the attributes provided in the body.
By providing a notificationMessage within the _meta block of the payload, the client can include a customized message to the user of the updated membership. In case of a group, the message will be sent to every user belonging to the group.
By including { "sendNotifications": false } within the _meta block of the payload, no notifications is send out at all.
id
integer
required path
Membership id
Example:1
200
OK
application/hal+json View_membershipModel {
"type": "object",
"example": {
"_links": {
"self": {
"href": "/api/v3/memberships/11",
"title": "Some user"
},
"schema": {
"href": "/api/v3/memberships/schema"
},
"update": {
"href": "/api/v3/memberships/11/form",
"method": "post"
},
"updateImmediately": {
"href": "/api/v3/memberships/11",
"method": "patch"
},
"project": {
"href": "/api/v3/projects/3",
"title": "A project"
},
"principal": {
"href": "/api/v3/users/4",
"title": "Some user"
},
"roles": [
{
"href": "/api/v3/roles/5",
"title": "Member"
},
{
"href": "/api/v3/roles/4",
"title": "Reader"
}
]
},
"_type": "Membership",
"id": 11,
"createdAt": "2015-03-20T12:56:56Z",
"updatedAt": "2018-12-20T18:16:11Z",
"_embedded": {
"project...": {
},
"principal...": {
},
"roles...": [
]
}
}
}
400
403
Returned if the client does not have sufficient permissions.
Required permission: Manage members in the membership’s project.
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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 membership does not exist or the client does not have sufficient permissions to see it.
Required permission: view member
Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
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
415
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
application/hal+json {
"_embedded": {
"details": {
"attribute": "roles"
}
},
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Roles has an unassignable role."
}
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 membership
delete /api/v3/memberships/{id}Deletes the membership.
id
integer
required path
Membership id
Example:1
204
Returned if the membership was successfully deleted
403
Returned if the client does not have sufficient permissions.
Required permission: manage members
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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 membership does not exist or the client does not have sufficient permissions to see it.
Required permission: view members
Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
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
415
Membership update form
post /api/v3/memberships/{id}/form id
integer
required path
Membership id
Example:1
200
OK
application/hal+json {
"_embedded": {
"payload": {
"_links": {
"roles": [
{
"href": "/api/v3/roles/4",
"title": "A role"
}
]
},
"_meta": {
"notificationMessage": {
"raw": "Alice, you can now also create work packages."
}
}
},
"schema": {
"_dependencies": [
],
"_links": {
},
"_type": "Schema",
"createdAt": {
"hasDefault": false,
"name": "Created on",
"required": true,
"type": "DateTime",
"writable": false
},
"id": {
"hasDefault": false,
"name": "ID",
"required": true,
"type": "Integer",
"writable": false
},
"notificationMessage": {
"hasDefault": false,
"location": "_meta",
"name": "Message",
"options": {
},
"required": false,
"type": "Formattable",
"writable": true
},
"principal": {
"_links": {
},
"hasDefault": false,
"name": "Principal",
"required": true,
"type": "Principal",
"writable": false
},
"project": {
"_links": {
},
"hasDefault": false,
"name": "Project",
"required": false,
"type": "Project",
"writable": false
},
"roles": {
"_links": {
"allowedValues": {
"href": "/api/v3/roles?filters=%5B%7B%22unit%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%22project%22%5D%7D%7D%5D"
}
},
"hasDefault": false,
"location": "_links",
"name": "Role",
"required": true,
"type": "[]Role",
"writable": true
},
"updatedAt": {
"hasDefault": false,
"name": "Updated on",
"required": true,
"type": "DateTime",
"writable": false
}
},
"validationErrors": {
}
},
"_links": {
"commit": {
"href": "/api/v3/memberships/5",
"method": "patch"
},
"self": {
"href": "/api/v3/memberships/5/form",
"method": "post"
},
"validate": {
"href": "/api/v3/memberships/5/form",
"method": "post"
}
},
"_type": "Form"
}
400
403
Returned if the client does not have sufficient permissions.
Required permission: manage versions in the version’s project
application/hal+json {
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
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
415
