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

Methods

List roles

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

filters
string

optional query

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

Example:
[{ "unit": { "operator": "=", "values": ["system"] }" }]

200

OK

{
  "_embedded": {
    "elements": [
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/3",
            "title": "Manager"
          }
        },
        "_type": "Role",
        "id": 3,
        "name": "Manager"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/2",
            "title": "Anonymous"
          }
        },
        "_type": "Role",
        "id": 2,
        "name": "Anonymous"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/5",
            "title": "Reader"
          }
        },
        "_type": "Role",
        "id": 5,
        "name": "Reader"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/4",
            "title": "Member"
          }
        },
        "_type": "Role",
        "id": 4,
        "name": "Member"
      },
      {
        "_links": {
          "self": {
            "href": "/api/v3/roles/1",
            "title": "Non member"
          }
        },
        "_type": "Role",
        "id": 1,
        "name": "Non member"
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/api/v3/roles"
    }
  },
  "_type": "Collection",
  "count": 5,
  "total": 5
}
RolesModel
{
  "type": "object",
  "example": {
    "_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"
      }
    }
  }
}

View role

Fetch an individual role.

id
integer

required path

Role id

Example:
1

200

OK

{
  "_links": {
    "self": {
      "href": "/api/v3/roles/3",
      "title": "Manager"
    }
  },
  "_type": "Role",
  "id": 3,
  "name": "Manager"
}
RoleModel
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "Role"
      ]
    },
    "id": {
      "type": "integer",
      "description": "Role id",
      "readOnly": true,
      "minimum": 1
    },
    "name": {
      "type": "string",
      "description": "Role name"
    },
    "_links": {
      "type": "object",
      "required": [
        "self"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This role\n\n**Resource**: Role",
              "readOnly": true
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "Role",
    "id": 3,
    "name": "Manager",
    "_links": {
      "self": {
        "href": "/api/v3/roles/3",
        "title": "Manager"
      }
    }
  }
}

403

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

Required permission: view members or manage members

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

404

Returned if the role does not exist.

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