openapi: 3.1.2
info:
description: "You're looking at the current **stable** documentation of the OpenProject APIv3. If you're interested in the current\ndevelopment version, please go to [github.com/opf](https://github.com/opf/openproject/tree/dev/docs/api/apiv3).\n\n## Introduction\n\nThe documentation for the APIv3 is written according to the [OpenAPI 3.1 Specification](https://swagger.io/specification/).\nYou can either view the static version of this documentation on the [website](https://www.openproject.org/docs/api/introduction/)\nor the interactive version, rendered with [OpenAPI Explorer](https://github.com/Rhosys/openapi-explorer/blob/main/README.md),\nin your OpenProject installation under `/api/docs`.\nIn the latter you can try out the various API endpoints directly interacting with our OpenProject data.\nMoreover you can access the specification source itself under `/api/v3/spec.json` and `/api/v3/spec.yml`\n(e.g. [here](https://community.openproject.org/api/v3/spec.yml)).\n\nThe APIv3 is a hypermedia REST API, a shorthand for \"Hypermedia As The Engine Of Application State\" (HATEOAS).\nThis means that each endpoint of this API will have links to other resources or actions defined in the resulting body.\n\nThese related resources and actions for any given resource will be context sensitive. For example, only actions that the\nauthenticated user can take are being rendered. This can be used to dynamically identify actions that the user might take for any\ngiven response.\n\nAs an example, if you fetch a work package through the [Work Package endpoint](https://www.openproject.org/docs/api/endpoints/work-packages/), the `update` link will only\nbe present when the user you authenticated has been granted a permission to update the work package in the assigned project.\n\n## HAL+JSON\n\nHAL is a simple format that gives a consistent and easy way to hyperlink between resources in your API.\nRead more in the following specification: [https://tools.ietf.org/html/draft-kelly-json-hal-08](https://tools.ietf.org/html/draft-kelly-json-hal-08)\n\n**OpenProject API implementation of HAL+JSON format** enriches JSON and introduces a few meta properties:\n\n- `_type` - specifies the type of the resource (e.g.: WorkPackage, Project)\n- `_links` - contains all related resource and action links available for the resource\n- `_embedded` - contains all embedded objects\n\nHAL does not guarantee that embedded resources are embedded in their full representation, they might as well be\npartially represented (e.g. some properties can be left out).\nHowever in this API you have the guarantee that whenever a resource is **embedded**, it is embedded in its **full representation**.\n\n## API response structure\n\nAll API responses contain a single HAL+JSON object, even collections of objects are technically represented by\na single HAL+JSON object that itself contains its members. More details on collections can be found\nin the [Collections Section](https://www.openproject.org/docs/api/collections/).\n\n## Authentication\n\nThe API supports the following authentication schemes:\n\n* Session-based authentication\n* API tokens\n * passed as Bearer token\n * passed via Basic auth\n* OAuth 2.0\n * using built-in authorization server\n * using an external authorization server (RFC 9068)\n\nDepending on the settings of the OpenProject instance many resources can be accessed without being authenticated.\nIn case the instance requires authentication on all requests the client will receive an **HTTP 401** status code\nin response to any request.\n\nOtherwise unauthenticated clients have all the permissions of the anonymous user.\n\n### Session-based authentication\n\nThis means you have to login to OpenProject via the Web-Interface to be authenticated in the API.\nThis method is well-suited for clients acting within the browser, like the Angular-Client built into OpenProject.\n\nIn this case, you always need to pass the HTTP header `X-Requested-With \"XMLHttpRequest\"` for authentication.\n\n### API token as bearer token\n\nUsers can authenticate towards the API v3 using an API token as a bearer token.\n\nFor example:\n\n```shell\nAPI_KEY=opapi-2519132cdf62dcf5a66fd96394672079f9e9cad1\ncurl -H \"Authorization: Bearer $API_KEY\" https://community.openproject.org/api/v3/users/42\n```\n\nUsers can generate API tokens on their account page.\n\n### API token through Basic Auth\n\nAPI tokens can also be used with basic auth, using the user name `apikey` (NOT your login) and the API token as the password.\n\nFor example:\n\n```shell\nAPI_KEY=opapi-2519132cdf62dcf5a66fd96394672079f9e9cad1\ncurl -u apikey:$API_KEY https://community.openproject.org/api/v3/users/42\n```\n\n### OAuth 2.0 authentication\n\nOpenProject allows authentication and authorization with OAuth2 with *Authorization code flow*, as well as *Client credentials* operation modes.\n\nTo get started, you first need to register an application in the OpenProject OAuth administration section of your installation.\nThis will save an entry for your application with a client unique identifier (`client_id`) and an accompanying secret key (`client_secret`).\n\nYou can then use one the following guides to perform the supported OAuth 2.0 flows:\n\n- [Authorization code flow](https://oauth.net/2/grant-types/authorization-code)\n\n- [Authorization code flow with PKCE](https://doorkeeper.gitbook.io/guides/ruby-on-rails/pkce-flow), recommended for clients unable to keep the client_secret confidential\n\n- [Client credentials](https://oauth.net/2/grant-types/client-credentials/) - Requires an application to be bound to an impersonating user for non-public access\n\n### OAuth 2.0 using an external authorization server\n\nThere is a possibility to use JSON Web Tokens (JWT) generated by an OIDC provider configured in OpenProject as a bearer token to do authenticated requests against the API.\nThe following requirements must be met:\n\n- OIDC provider must be configured in OpenProject with **jwks_uri**\n- JWT must be signed using RSA algorithm\n- JWT **iss** claim must be equal to OIDC provider **issuer**\n- JWT **aud** claim must contain the OpenProject **client ID** used at the OIDC provider\n- JWT **scope** claim must include a valid scope to access the desired API (e.g. `api_v3` for APIv3)\n- JWT must be actual (neither expired or too early to be used)\n- JWT must be passed in Authorization header like: `Authorization: Bearer {jwt}`\n- User from **sub** claim must be linked to OpenProject before (e.g. by logging in), otherwise it will be not authenticated\n\nIn more general terms, OpenProject should be compliant to [RFC 9068](https://www.rfc-editor.org/rfc/rfc9068) when validating access tokens.\n\n### Why not username and password?\n\nThe simplest way to do basic auth would be to use a user's username and password naturally.\nHowever, OpenProject already has supported API keys in the past for the API v2, though not through basic auth.\n\nUsing **username and password** directly would have some advantages:\n\n* It is intuitive for the user who then just has to provide those just as they would when logging into OpenProject.\n\n* No extra logic for token management necessary.\n\nOn the other hand using **API keys** has some advantages too, which is why we went for that:\n\n* If compromised while saved on an insecure client the user only has to regenerate the API key instead of changing their password, too.\n\n* They are naturally long and random which makes them invulnerable to dictionary attacks and harder to crack in general.\n\nMost importantly users may not actually have a password to begin with. Specifically when they have registered\nthrough an OpenID Connect provider.\n\n## Cross-Origin Resource Sharing (CORS)\n\nBy default, the OpenProject API is _not_ responding with any CORS headers.\nIf you want to allow cross-domain AJAX calls against your OpenProject instance, you need to enable CORS headers being returned.\n\nPlease see [our API settings documentation](https://www.openproject.org/docs/system-admin-guide/api-and-webhooks/) on\nhow to selectively enable CORS.\n\n## Allowed HTTP methods\n\n- `GET` - Get a single resource or collection of resources\n\n- `POST` - Create a new resource or perform\n\n- `PATCH` - Update a resource\n\n- `DELETE` - Delete a resource\n\n## Compression\n\nResponses are compressed if requested by the client. Currently [gzip](https://www.gzip.org/) and [deflate](https://tools.ietf.org/html/rfc1951)\nare supported. The client signals the desired compression by setting the [`Accept-Encoding` header](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.3).\nIf no `Accept-Encoding` header is send, `Accept-Encoding: identity` is assumed which will result in the API responding uncompressed."
title: OpenProject API V3 (Stable) Actions & Capabilities Memberships API
version: '3'
servers:
- url: https://qa.openproject-edge.com
description: Edge QA instance
- url: https://qa.openproject-stage.com
description: Staging instance
- url: https://community.openproject.org
description: Community instance
security:
- BasicAuth: []
tags:
- description: '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 | |'
name: Memberships
paths:
/api/v3/memberships:
get:
summary: List memberships
operationId: list_memberships
tags:
- Memberships
description: '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*).'
parameters:
- name: filters
in: query
required: false
schema:
type: string
description: "JSON specifying filter conditions.\nAccepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)\nendpoint. Currently supported filters are:\n\n+ any_name_attribute: filters memberships based on the name of the principal. All possible name variants\n (and also email and login) are searched.\n+ blocked: reduces the result set to all memberships that are temporarily blocked or that are not blocked\n temporarily.\n+ group: filters memberships based on the name of a group. The group however is not the principal used for\n filtering. Rather, the memberships of the group are used as the filter values.\n+ name: filters memberships based on the name of the principal. Note that only the name is used which depends\n on a setting in the OpenProject instance.\n+ principal: filters memberships based on the id of the principal.\n+ project: filters memberships based on the id of the project.\n+ role: filters memberships based on the id of any role assigned to the membership.\n+ status: filters memberships based on the status of the principal.\n+ created_at: filters memberships based on the time the membership was created.\n+ updated_at: filters memberships based on the time the membership was updated last."
examples:
name-filter:
summary: Filtering on the name of the principal
value: '[{ "name": { "operator": "=", "values": ["A User"] }" }]'
global-memberships:
summary: Get memberships for global roles
value: '[{ "project": { "operator": "!*", "values": null }" }]'
- name: sortBy
in: query
required: false
schema:
default: '[["id", "asc"]]'
type: string
description: "JSON specifying sort criteria.\nAccepts the same format as returned by the [queries](https://www.openproject.org/docs/api/endpoints/queries/)\nendpoint. Currently supported sorts are:\n\n+ id: Sort by primary key\n+ name: Sort by the name of the principal. Note that this depends on the setting for how the name is to be\n displayed at least for users.\n+ email: Sort by the email address of the principal. Groups and principal users, which do not have an email,\n are sorted last.\n+ status: Sort by the status of the principal. Groups and principal users, which do not have a status, are\n sorted together with the active users.\n+ created_at: Sort by membership creation datetime\n+ updated_at: Sort by the time the membership was updated last"
example: '[["id", "asc"]]'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/MembershipCollectionModel'
examples:
simple membership collection:
$ref: '#/components/examples/MembershipSimpleCollectionResponse'
'400':
$ref: '#/components/responses/InvalidQuery'
'403':
description: Returned if the client is not logged in and login is required.
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to view this resource.
post:
summary: Create a membership
operationId: create_membership
tags:
- Memberships
description: '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.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipWriteModel'
examples:
global role:
$ref: '#/components/examples/MembershipCreateRequestGlobalRole'
no notification:
$ref: '#/components/examples/MembershipCreateRequestNoNotification'
custom message:
$ref: '#/components/examples/MembershipCreateRequestCustomMessage'
responses:
'201':
description: Created
content:
application/hal+json:
schema:
$ref: '#/components/schemas/MembershipReadModel'
examples:
simple membership:
$ref: '#/components/examples/MembershipSimpleResponse'
'400':
$ref: '#/components/responses/InvalidRequestBody'
'403':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to access this resource.
description: 'Returned if the client does not have sufficient permissions.
**Required permission:** Manage members'
'406':
$ref: '#/components/responses/MissingContentType'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'422':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_embedded:
details:
attribute: project
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
message: Project can't be blank.
description: 'Returned if:
- a constraint for a property was violated (`PropertyConstraintViolation`)'
/api/v3/memberships/available_projects:
get:
summary: Available projects for memberships
operationId: get_memberships_available_projects
tags:
- Memberships
description: '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.'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ProjectCollectionModel'
examples:
simple project collection:
$ref: '#/components/examples/ProjectCollection'
'403':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to access this resource.
description: 'Returned if the client does not have sufficient permissions.
**Required permission:** manage members'
/api/v3/memberships/form:
post:
summary: Form create membership
operationId: form_create_membership
tags:
- Memberships
description: 'Requests and validates the creation form for memberships. The request payload, if sent, is validated. The form
endpoint itself does not create a membership.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipWriteModel'
examples:
global role:
$ref: '#/components/examples/MembershipCreateRequestGlobalRole'
no notification:
$ref: '#/components/examples/MembershipCreateRequestNoNotification'
custom message:
$ref: '#/components/examples/MembershipCreateRequestCustomMessage'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/MembershipFormModel'
examples:
form:
$ref: '#/components/examples/MembershipFormResponse'
'400':
$ref: '#/components/responses/InvalidRequestBody'
'403':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to access this resource.
description: 'Returned if the client does not have sufficient permissions.
**Required permission:** manage memberships in any project'
'406':
$ref: '#/components/responses/MissingContentType'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
/api/v3/memberships/schema:
get:
summary: Schema membership
operationId: get_membership_schema
tags:
- Memberships
description: Retrieves the schema for the membership resource object.
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/MembershipSchemaModel'
examples:
schema:
$ref: '#/components/examples/MembershipSchemaResponse'
'403':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
response:
value:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to access this resource.
description: 'Returned if the client does not have sufficient permissions to see the schema.
**Required permission:** manage members or view memberships on any project'
/api/v3/memberships/{id}:
delete:
summary: Delete membership
operationId: delete_membership
tags:
- Memberships
description: Deletes the membership.
parameters:
- name: id
description: Membership id
in: path
required: true
example: 1
schema:
type: integer
responses:
'204':
description: Returned if the membership was successfully deleted
'403':
description: 'Returned if the client does not have sufficient permissions.
**Required permission:** manage members'
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to access this resource.
'404':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
message: The requested resource could not be found.
description: '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.*'
'406':
$ref: '#/components/responses/MissingContentType'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
get:
summary: Get a membership
operationId: get_membership
description: Retrieves a membership resource identified by the given id.
tags:
- Memberships
parameters:
- name: id
description: Membership id
in: path
required: true
example: 1
schema:
type: integer
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/MembershipReadModel'
examples:
simple membership:
$ref: '#/components/examples/MembershipSimpleResponse'
'404':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
message: The requested resource could not be found.
description: '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.*'
patch:
summary: Update membership
operationId: update_membership
description: '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.'
tags:
- Memberships
parameters:
- name: id
description: Membership id
in: path
required: true
example: 1
schema:
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipWriteModel'
examples:
add roles:
$ref: '#/components/examples/MembershipUpdateAdditionalRoles'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/MembershipReadModel'
examples:
simple membership:
$ref: '#/components/examples/MembershipSimpleResponse'
'400':
$ref: '#/components/responses/InvalidRequestBody'
'403':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to access this resource.
description: 'Returned if the client does not have sufficient permissions.
**Required permission:** Manage members in the membership''s project.'
headers: {}
'404':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
message: The requested resource could not be found.
description: '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.*'
'406':
$ref: '#/components/responses/MissingContentType'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'422':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_embedded:
details:
attribute: roles
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
message: Roles has an unassignable role.
description: 'Returned if:
* a constraint for a property was violated (`PropertyConstraintViolation`)'
/api/v3/memberships/{id}/form:
post:
summary: Form update membership
operationId: form_update_membership
tags:
- Memberships
description: '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.'
parameters:
- name: id
description: Membership id
in: path
required: true
example: 1
schema:
type: integer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipWriteModel'
examples:
no notification:
$ref: '#/components/examples/MembershipCreateRequestNoNotification'
custom message:
$ref: '#/components/examples/MembershipCreateRequestCustomMessage'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/MembershipReadModel'
examples:
simple membership:
$ref: '#/components/examples/MembershipSimpleResponse'
'400':
$ref: '#/components/responses/InvalidRequestBody'
'403':
content:
application/hal+json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
_type: Error
errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
message: You are not authorized to access this resource.
description: 'Returned if the client does not have sufficient permissions.
**Required permission:** manage versions in the version''s project'
'406':
$ref: '#/components/responses/MissingContentType'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
components:
schemas:
CollectionModel:
type: object
required:
- _type
- total
- count
-
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openproject/refs/heads/main/openapi/openproject-memberships-api-openapi.yml