Roles

When principals (groups or users) are assigned to a project, they are receive roles in that project. Roles regulate access to specific resources by having permissions configured for them.

Currently, this is only a stub.

Linked Properties

Link Description Type Constraints Supported operations
self This role Role not null READ

Local Properties

Property Description Type Constraints Supported operations
id Role id Integer x > 0 READ
name Role name String not null READ

Role 

View role
/api/v3/roles/{id}

Fetch an individual role.

  • Parameters
  • id
    integer (required) Example: 1

    role id

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Role",
      "id": 3,
      "name": "Manager",
      "_links": {
        "self": {
          "href": "/api/v3/roles/3",
          "title": "Manager"
        }
      }
    }
  • Response  403
  • Returned if the client does not have sufficient permissions to see roles.

    Required permission: view members or manage members

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
      "message": "You are not authorized to view this resource."
    }
  • Response  404
  • Returned if the role does not exist.

    Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Error",
      "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
      "message": "The requested resource could not be found."
    }

Roles 

List roles
/api/v3/roles{?filters}

List all defined roles. This includes built in roles like ‘Anonymous’ and ‘Non member’.

  • Parameters
  • filters
    string (optional) Example: [{ "unit": { "operator": "=", "values": ["system"] }" }]

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

    • grantable: filters roles based on whether they are selectable for a membership

    • unit: filters roles based on the unit (‘project’ or ‘system’) for which they are selectable for a membership

  • Response  200
  • Headers
    Content-Type: application/hal+json
    Body
    {
      "_type": "Collection",
      "total": 5,
      "count": 5,
      "_embedded": {
        "elements": [
          {
            "_type": "Role",
            "id": 3,
            "name": "Manager",
            "_links": {
              "self": {
                "href": "/api/v3/roles/3",
                "title": "Manager"
              }
            }
          },
          {
            "_type": "Role",
            "id": 2,
            "name": "Anonymous",
            "_links": {
              "self": {
                "href": "/api/v3/roles/2",
                "title": "Anonymous"
              }
            }
          },
          {
            "_type": "Role",
            "id": 5,
            "name": "Reader",
            "_links": {
              "self": {
                "href": "/api/v3/roles/5",
                "title": "Reader"
              }
            }
          },
          {
            "_type": "Role",
            "id": 4,
            "name": "Member",
            "_links": {
              "self": {
                "href": "/api/v3/roles/4",
                "title": "Member"
              }
            }
          },
          {
            "_type": "Role",
            "id": 1,
            "name": "Non member",
            "_links": {
              "self": {
                "href": "/api/v3/roles/1",
                "title": "Non member"
              }
            }
          }
        ]
      },
      "_links": {
        "self": {
          "href": "/api/v3/roles"
        }
      }
    }