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