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

Returns 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

{
  "_type": "Collection",
  "total": 2,
  "count": 2,
  "pageSize": 20,
  "offset": 1,
  "_embedded": {
    "elements": [
      {
        "_type": "Membership",
        "id": 11,
        "createdAt": "2015-03-20T12:56:56.643Z",
        "updatedAt": "2018-12-20T18:16:11.643Z",
        "_links": {
          "self": {
            "href": "/api/v3/memberships/11",
            "title": "Darth Vader"
          },
          "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": "Death Start v3"
          },
          "principal": {
            "href": "/api/v3/users/5",
            "title": "Darth Vader"
          },
          "roles": [
            {
              "href": "/api/v3/roles/4",
              "title": "Sith Lord"
            }
          ]
        }
      },
      {
        "_type": "Membership",
        "id": 12,
        "_hint": "Membership resource shortened for brevity"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/memberships"
    },
    "jumpTo": {
      "href": "/api/v3/memberships?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/memberships?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    },
    "nextByOffset": {
      "href": "/api/v3/memberships?filters=%5B%5D&offset=2&pageSize=20"
    }
  }
}
MembershipCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/PaginatedCollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_embedded"
      ],
      "properties": {
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/MembershipReadModel"
              }
            }
          }
        }
      }
    }
  ]
}

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."
    }
  }
}

403

Returned if the client is not logged in and login is required.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to view 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."
    }
  }
}

Create a membership

Creates 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.

No parameters
{
  "_links": {
    "type": "object",
    "properties": {
      "principal": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The principal that is to get a membership.\n\n**Resource**: Principal"
          }
        ]
      },
      "roles": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "A role the principal has.\n\n**Resource**: Role"
            }
          ]
        }
      },
      "project": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The project that is to get a membership. If no project is given, the principal's membership is supposed\nto be global.\n\n**Resource**: Project"
          }
        ]
      }
    }
  },
  "_meta": {
    "type": "object",
    "properties": {
      "notificationMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Formattable"
          },
          {
            "description": "A customised notification message, which will overwrite the standard notification."
          }
        ]
      },
      "sendNotification": {
        "type": "boolean",
        "description": "Set to false, if no notification should get sent.",
        "default": true
      }
    }
  }
}

201

Created

{
  "_type": "Membership",
  "id": 11,
  "createdAt": "2015-03-20T12:56:56.626Z",
  "updatedAt": "2018-12-20T18:16:11.563Z",
  "_embedded": {
    "project": {
      "_type": "Project",
      "id": 3,
      "_hint": "Project resource shortened for brevity"
    },
    "principal": {
      "_type": "User",
      "id": 5,
      "_hint": "User resource shortened for brevity"
    },
    "roles": [
      {
        "_type": "Role",
        "id": 4,
        "_hint": "Roles resource shortened for brevity"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/memberships/11",
      "title": "Darth Vader"
    },
    "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": "Death Start v3"
    },
    "principal": {
      "href": "/api/v3/users/5",
      "title": "Darth Vader"
    },
    "roles": [
      {
        "href": "/api/v3/roles/4",
        "title": "Sith Lord"
      }
    ]
  }
}
MembershipReadModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "createdAt",
    "updatedAt",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Membership"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The membership's id",
      "minimum": 1
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the membership was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the membership was last updated."
    },
    "_embedded": {
      "type": "object",
      "properties": {
        "project": {
          "$ref": "#/components/schemas/ProjectModel"
        },
        "principal": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/UserModel"
            },
            {
              "$ref": "#/components/schemas/GroupModel"
            }
          ]
        },
        "roles": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/RoleModel"
          }
        }
      }
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "project",
        "principal",
        "roles"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This membership.\n\n**Resource**: Membership"
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This membership schema.\n\n**Resource**: Schema"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint for updating the membership.\n\n# Conditions\n\n**Permission**: manage_members"
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint for updating the membership without form validation.\n\n# Conditions\n\n**Permission**: manage_members"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the membership is related to.\n\n**Resource**: Project"
            }
          ]
        },
        "principal": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The principal the membership is related to.\n\n**Resource**: Principal"
            }
          ]
        },
        "roles": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A role the principal has.\n\n**Resource**: Role"
              }
            ]
          }
        }
      }
    }
  }
}

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 members

{
  "_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

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": "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

Gets 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.

No parameters

200

OK

{
  "_type": "Collection",
  "count": 2,
  "total": 2,
  "pageSize": 20,
  "offset": 1,
  "_embedded": {
    "elements": [
      {
        "_hint": "Project resource shortened for brevity",
        "id": 1,
        "identifier": "initialproject",
        "name": "DeathStar construction",
        "active": true,
        "public": true
      },
      {
        "_hint": "Project resource shortened for brevity",
        "id": 2,
        "identifier": "mysecret",
        "name": "Palpatine's secret plan",
        "active": true,
        "public": false
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/projects?filters=%5B%5D&offset=1&pageSize=20"
    },
    "jumpTo": {
      "href": "/api/v3/projects?filters=%5B%5D&offset=%7Boffset%7D&pageSize=20",
      "templated": true
    },
    "changeSize": {
      "href": "/api/v3/projects?filters=%5B%5D&offset=1&pageSize=%7Bsize%7D",
      "templated": true
    },
    "representations": [
      {
        "href": "/projects.csv?filters=%5B%5D&offset=1&pageSize=20",
        "identifier": "csv",
        "type": "text/csv",
        "title": "CSV"
      },
      {
        "href": "/projects.xls?filters=%5B%5D&offset=1&pageSize=20",
        "identifier": "xls",
        "type": "application/vnd.ms-excel",
        "title": "XLS"
      }
    ]
  }
}
ProjectCollectionModel
{
  "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 project collection\n\n**Resource**: ProjectStorageCollectionModel"
                }
              ]
            },
            "representations": {
              "type": "array",
              "items": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Link"
                  },
                  {
                    "description": "A project collection representation in a specific file format."
                  }
                ]
              }
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ProjectModel"
              }
            }
          }
        }
      }
    }
  ]
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage members

{
  "_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."
    }
  }
}

Form create membership

Requests and validates the creation form for memberships. The request payload, if sent, is validated. The form endpoint itself does not create a membership.

No parameters
{
  "_links": {
    "type": "object",
    "properties": {
      "principal": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The principal that is to get a membership.\n\n**Resource**: Principal"
          }
        ]
      },
      "roles": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "A role the principal has.\n\n**Resource**: Role"
            }
          ]
        }
      },
      "project": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The project that is to get a membership. If no project is given, the principal's membership is supposed\nto be global.\n\n**Resource**: Project"
          }
        ]
      }
    }
  },
  "_meta": {
    "type": "object",
    "properties": {
      "notificationMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Formattable"
          },
          {
            "description": "A customised notification message, which will overwrite the standard notification."
          }
        ]
      },
      "sendNotification": {
        "type": "boolean",
        "description": "Set to false, if no notification should get sent.",
        "default": true
      }
    }
  }
}

200

OK

{
  "_type": "Form",
  "_embedded": {
    "payload": {
      "_meta": {
        "notificationMessage": {
          "format": "markdown",
          "raw": "*Hallo*",
          "html": "<p class=\"op-uc-p\"><em>Hallo</em></p>"
        }
      },
      "_links": {
        "project": {
          "href": "/api/v3/projects/21",
          "title": "Death Star v3"
        },
        "principal": {
          "href": "/api/v3/users/14",
          "title": "Mara Jade"
        },
        "roles": [

        ]
      }
    },
    "schema": {
      "_type": "Schema",
      "_hint": "Schema resource shortened for brevity"
    },
    "validationErrors": {
      "roles": {
        "_type": "Error",
        "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
        "message": "Roles need to be assigned.",
        "_embedded": {
          "details": {
            "attribute": "roles"
          }
        }
      }
    }
  },
  "_links": {
    "self": {
      "href": "/api/v3/memberships/form",
      "method": "post"
    },
    "validate": {
      "href": "/api/v3/memberships/form",
      "method": "post"
    }
  }
}
MembershipFormModel
{
  "type": "object",
  "required": [
    "_type",
    "_embedded",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Form"
      ]
    },
    "_embedded": {
      "type": "object",
      "required": [
        "payload",
        "schema",
        "validationError"
      ],
      "properties": {
        "payload": {
          "$ref": "#/components/schemas/MembershipWriteModel"
        },
        "schema": {
          "$ref": "#/components/schemas/MembershipSchemaModel"
        },
        "validationError": {
          "type": "object",
          "properties": {
            "base": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "principal": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "roles": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "validate",
        "commit"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This form request.\n\n**Resource**: Form"
            }
          ]
        },
        "validate": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "The endpoint to validate the membership payload."
              }
            ]
          }
        },
        "commit": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint to create the membership with the same payload, as sent to the form.\n\n**Resource**: Membership"
            }
          ]
        }
      }
    }
  }
}

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 memberships in any project

{
  "_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

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."
    }
  }
}

Schema membership

Retrieves the schema for the membership resource object.

No parameters

200

OK

{
  "_type": "Schema",
  "_dependencies": [

  ],
  "id": {
    "type": "Integer",
    "name": "ID",
    "required": true,
    "hasDefault": false,
    "writable": false,
    "options": {
    }
  },
  "createdAt": {
    "type": "DateTime",
    "name": "Created on",
    "required": true,
    "hasDefault": false,
    "writable": false,
    "options": {
    }
  },
  "updatedAt": {
    "type": "DateTime",
    "name": "Updated on",
    "required": true,
    "hasDefault": false,
    "writable": false,
    "options": {
    }
  },
  "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": {
      "allowedValues": {
        "href": "/api/v3/memberships/available_projects?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%21%22%2C%22values%22%3A%5B%2214%22%5D%7D%7D%5D"
      }
    }
  },
  "principal": {
    "type": "Principal",
    "name": "Principal",
    "required": true,
    "hasDefault": false,
    "writable": true,
    "location": "_links",
    "_links": {
      "allowedValues": {
        "href": "/api/v3/principals?filters=%5B%7B%22status%22%3A%7B%22operator%22%3A%22%21%22%2C%22values%22%3A%5B%223%22%5D%7D%7D%2C%7B%22member%22%3A%7B%22operator%22%3A%22%21%22%2C%22values%22%3A%5B%2221%22%5D%7D%7D%5D"
      }
    }
  },
  "roles": {
    "type": "[]Role",
    "name": "Role",
    "required": true,
    "hasDefault": false,
    "writable": true,
    "location": "_links",
    "_links": {
      "allowedValues": {
        "href": "/api/v3/roles"
      }
    }
  },
  "_links": {
    "self": {
      "href": "/api/v3/memberships/schema"
    }
  }
}
MembershipSchemaModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/SchemaModel"
    },
    {
      "type": "object",
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "notificationMessage",
        "project",
        "principal",
        "roles"
      ],
      "properties": {
        "id": {
          "$ref": "#/components/schemas/SchemaPropertyModel"
        },
        "createdAt": {
          "$ref": "#/components/schemas/SchemaPropertyModel"
        },
        "updatedAt": {
          "$ref": "#/components/schemas/SchemaPropertyModel"
        },
        "notificationMessage": {
          "$ref": "#/components/schemas/SchemaPropertyModel"
        },
        "project": {
          "$ref": "#/components/schemas/SchemaPropertyModel"
        },
        "principal": {
          "$ref": "#/components/schemas/SchemaPropertyModel"
        },
        "roles": {
          "$ref": "#/components/schemas/SchemaPropertyModel"
        }
      }
    }
  ]
}

403

Returned if the client does not have sufficient permissions to see the schema.

Required permission: manage members or view memberships on any project

{
  "_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."
    }
  }
}

Get a membership

Retrieves a membership resource identified by the given id.

id
integer

required path

Membership id

Example:
1

200

OK

{
  "_type": "Membership",
  "id": 11,
  "createdAt": "2015-03-20T12:56:56.626Z",
  "updatedAt": "2018-12-20T18:16:11.563Z",
  "_embedded": {
    "project": {
      "_type": "Project",
      "id": 3,
      "_hint": "Project resource shortened for brevity"
    },
    "principal": {
      "_type": "User",
      "id": 5,
      "_hint": "User resource shortened for brevity"
    },
    "roles": [
      {
        "_type": "Role",
        "id": 4,
        "_hint": "Roles resource shortened for brevity"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/memberships/11",
      "title": "Darth Vader"
    },
    "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": "Death Start v3"
    },
    "principal": {
      "href": "/api/v3/users/5",
      "title": "Darth Vader"
    },
    "roles": [
      {
        "href": "/api/v3/roles/4",
        "title": "Sith Lord"
      }
    ]
  }
}
MembershipReadModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "createdAt",
    "updatedAt",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Membership"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The membership's id",
      "minimum": 1
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the membership was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the membership was last updated."
    },
    "_embedded": {
      "type": "object",
      "properties": {
        "project": {
          "$ref": "#/components/schemas/ProjectModel"
        },
        "principal": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/UserModel"
            },
            {
              "$ref": "#/components/schemas/GroupModel"
            }
          ]
        },
        "roles": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/RoleModel"
          }
        }
      }
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "project",
        "principal",
        "roles"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This membership.\n\n**Resource**: Membership"
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This membership schema.\n\n**Resource**: Schema"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint for updating the membership.\n\n# Conditions\n\n**Permission**: manage_members"
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint for updating the membership without form validation.\n\n# Conditions\n\n**Permission**: manage_members"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the membership is related to.\n\n**Resource**: Project"
            }
          ]
        },
        "principal": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The principal the membership is related to.\n\n**Resource**: Principal"
            }
          ]
        },
        "roles": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A role the principal has.\n\n**Resource**: Role"
              }
            ]
          }
        }
      }
    }
  }
}

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.

{
  "_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

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

{
  "_links": {
    "type": "object",
    "properties": {
      "principal": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The principal that is to get a membership.\n\n**Resource**: Principal"
          }
        ]
      },
      "roles": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "A role the principal has.\n\n**Resource**: Role"
            }
          ]
        }
      },
      "project": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The project that is to get a membership. If no project is given, the principal's membership is supposed\nto be global.\n\n**Resource**: Project"
          }
        ]
      }
    }
  },
  "_meta": {
    "type": "object",
    "properties": {
      "notificationMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Formattable"
          },
          {
            "description": "A customised notification message, which will overwrite the standard notification."
          }
        ]
      },
      "sendNotification": {
        "type": "boolean",
        "description": "Set to false, if no notification should get sent.",
        "default": true
      }
    }
  }
}

200

OK

{
  "_type": "Membership",
  "id": 11,
  "createdAt": "2015-03-20T12:56:56.626Z",
  "updatedAt": "2018-12-20T18:16:11.563Z",
  "_embedded": {
    "project": {
      "_type": "Project",
      "id": 3,
      "_hint": "Project resource shortened for brevity"
    },
    "principal": {
      "_type": "User",
      "id": 5,
      "_hint": "User resource shortened for brevity"
    },
    "roles": [
      {
        "_type": "Role",
        "id": 4,
        "_hint": "Roles resource shortened for brevity"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/memberships/11",
      "title": "Darth Vader"
    },
    "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": "Death Start v3"
    },
    "principal": {
      "href": "/api/v3/users/5",
      "title": "Darth Vader"
    },
    "roles": [
      {
        "href": "/api/v3/roles/4",
        "title": "Sith Lord"
      }
    ]
  }
}
MembershipReadModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "createdAt",
    "updatedAt",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Membership"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The membership's id",
      "minimum": 1
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the membership was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the membership was last updated."
    },
    "_embedded": {
      "type": "object",
      "properties": {
        "project": {
          "$ref": "#/components/schemas/ProjectModel"
        },
        "principal": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/UserModel"
            },
            {
              "$ref": "#/components/schemas/GroupModel"
            }
          ]
        },
        "roles": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/RoleModel"
          }
        }
      }
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "project",
        "principal",
        "roles"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This membership.\n\n**Resource**: Membership"
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This membership schema.\n\n**Resource**: Schema"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint for updating the membership.\n\n# Conditions\n\n**Permission**: manage_members"
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint for updating the membership without form validation.\n\n# Conditions\n\n**Permission**: manage_members"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the membership is related to.\n\n**Resource**: Project"
            }
          ]
        },
        "principal": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The principal the membership is related to.\n\n**Resource**: Principal"
            }
          ]
        },
        "roles": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A role the principal has.\n\n**Resource**: Role"
              }
            ]
          }
        }
      }
    }
  }
}

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 members in the membership’s project.

{
  "_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.

{
  "_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

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": "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

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

{
  "_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.

{
  "_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

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."
    }
  }
}

Form update membership

Requests and validates the update form for a membership identified by the given id. The request payload, if sent, is validated. The form endpoint itself does not change the membership.

id
integer

required path

Membership id

Example:
1

{
  "_links": {
    "type": "object",
    "properties": {
      "principal": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The principal that is to get a membership.\n\n**Resource**: Principal"
          }
        ]
      },
      "roles": {
        "type": "array",
        "items": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "A role the principal has.\n\n**Resource**: Role"
            }
          ]
        }
      },
      "project": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The project that is to get a membership. If no project is given, the principal's membership is supposed\nto be global.\n\n**Resource**: Project"
          }
        ]
      }
    }
  },
  "_meta": {
    "type": "object",
    "properties": {
      "notificationMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Formattable"
          },
          {
            "description": "A customised notification message, which will overwrite the standard notification."
          }
        ]
      },
      "sendNotification": {
        "type": "boolean",
        "description": "Set to false, if no notification should get sent.",
        "default": true
      }
    }
  }
}

200

OK

{
  "_type": "Membership",
  "id": 11,
  "createdAt": "2015-03-20T12:56:56.626Z",
  "updatedAt": "2018-12-20T18:16:11.563Z",
  "_embedded": {
    "project": {
      "_type": "Project",
      "id": 3,
      "_hint": "Project resource shortened for brevity"
    },
    "principal": {
      "_type": "User",
      "id": 5,
      "_hint": "User resource shortened for brevity"
    },
    "roles": [
      {
        "_type": "Role",
        "id": 4,
        "_hint": "Roles resource shortened for brevity"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/memberships/11",
      "title": "Darth Vader"
    },
    "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": "Death Start v3"
    },
    "principal": {
      "href": "/api/v3/users/5",
      "title": "Darth Vader"
    },
    "roles": [
      {
        "href": "/api/v3/roles/4",
        "title": "Sith Lord"
      }
    ]
  }
}
MembershipReadModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "createdAt",
    "updatedAt",
    "_links"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Membership"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The membership's id",
      "minimum": 1
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the membership was created."
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "The time the membership was last updated."
    },
    "_embedded": {
      "type": "object",
      "properties": {
        "project": {
          "$ref": "#/components/schemas/ProjectModel"
        },
        "principal": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/UserModel"
            },
            {
              "$ref": "#/components/schemas/GroupModel"
            }
          ]
        },
        "roles": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/RoleModel"
          }
        }
      }
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "schema",
        "project",
        "principal",
        "roles"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This membership.\n\n**Resource**: Membership"
            }
          ]
        },
        "schema": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This membership schema.\n\n**Resource**: Schema"
            }
          ]
        },
        "update": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint for updating the membership.\n\n# Conditions\n\n**Permission**: manage_members"
            }
          ]
        },
        "updateImmediately": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The endpoint for updating the membership without form validation.\n\n# Conditions\n\n**Permission**: manage_members"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project the membership is related to.\n\n**Resource**: Project"
            }
          ]
        },
        "principal": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The principal the membership is related to.\n\n**Resource**: Principal"
            }
          ]
        },
        "roles": {
          "type": "array",
          "items": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Link"
              },
              {
                "description": "A role the principal has.\n\n**Resource**: Role"
              }
            ]
          }
        }
      }
    }
  }
}

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 versions in the version’s project

{
  "_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

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."
    }
  }
}