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

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

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