{
  "openapi": "3.0.3",
  "info": {
    "title": "Access roles API",
    "version": "SaaS",
    "termsOfService": "https://developers.topdesk.com/legal.html",
    "contact": {
      "name": "TOPdesk",
      "url": "https://www.topdesk.com",
      "email": "info@topdesk.com"
    },
    "description": "Access roles are the replacement of `Permission Groups`. Each `Role` has multiple `Role Configurations`, detailing its checked permissions. Role configurations are split by `origin`. An origin corresponds to a functionality in the TOPdesk application.\n\nAt this moment only GET requests are supported."
  },
  "servers": [
    {
      "url": "https://{topdesk_host}/services/permissions",
      "variables": {
        "topdesk_host": {
          "default": "customer.topdesk.net"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Roles",
      "description": "A role defines a set of permissions. Users can be assigned to one or more roles. If a user is assigned to multiple roles, they get the permissions of all their roles combined."
    },
    {
      "name": "RoleConfigurations",
      "description": "A roleConfiguration is a map between a role and the permissions that are set for this role, for a specific functionality."
    },
    {
      "name": "Reporting",
      "description": "The reporting endpoint(s) compliant with the OData reporting layer"
    }
  ],
  "paths": {
    "/roles": {
      "get": {
        "tags": [
          "Roles"
        ],
        "summary": "Retrieve a list of roles",
        "description": "Retrieves a list of roles, filtered by the supplied parameters. Permission group read permission is required.",
        "security": [
          {
            "BasicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "archived",
            "in": "query",
            "description": "Return only roles that are archived or not archived.",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "licensed",
            "in": "query",
            "description": "Return only roles that are licensed or not licensed.",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "fields",
            "in": "query",
            "description": "Fields to include in the response, separated by comma. The option 'all' returns all allowed fields.",
            "required": false,
            "schema": {
              "type": "string",
              "default": "_links,_embedded.item._links,_embedded.item.id,_embedded.item.name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoleListResultDto"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated or invalid authentication token."
          },
          "403": {
            "description": "No permission to access the data. Permission group read permission is required."
          }
        }
      }
    },
    "/roles/{id}": {
      "get": {
        "tags": [
          "Roles"
        ],
        "summary": "Retrieve a role by its id",
        "description": "Retrieves a single role. Permission group read permission is required.",
        "security": [
          {
            "BasicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The id of the role.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "description": "The ETag of the resource as returned in a previous request. This is used to determine if the resource was modified since the previous request. If it was not, the endpoint will respond with a 304.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoleResultDto"
                }
              }
            },
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "The ETag of the resource, uniquely identifying it."
              }
            }
          },
          "304": {
            "description": "The resource was not modified since the previous request. This is determined using the ETag supplied in the If-None-Match header."
          },
          "401": {
            "description": "Not authenticated or invalid authentication token."
          },
          "403": {
            "description": "No permission to access the data. Permission group read permission is required."
          },
          "404": {
            "description": "Role not found."
          }
        }
      }
    },
    "/roleConfigurations": {
      "get": {
        "tags": [
          "RoleConfigurations"
        ],
        "summary": "Retrieves a list of roleConfigurations",
        "description": "Retrieve all roleConfigurations or all roleConfigurations for a specific list of roles.",
        "security": [
          {
            "BasicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "roleId",
            "in": "query",
            "description": "Restricts the result to only the specified list of roles.",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string",
                "format": "uuid"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoleConfigurationListResultDto"
                }
              }
            },
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "The ETag of the resource, uniquely identifying it."
              }
            }
          },
          "304": {
            "description": "The resource was not modified since the previous request. This is determined using the ETag supplied in the If-None-Match header."
          },
          "401": {
            "description": "Not authenticated or invalid authentication token."
          },
          "403": {
            "description": "No permission to access the data. Permission group read permission is required."
          }
        }
      }
    },
    "/roleConfigurations/{id}": {
      "get": {
        "tags": [
          "RoleConfigurations"
        ],
        "summary": "Retrieve the roleConfiguration by id",
        "description": "Retrieves a permission configuration.",
        "security": [
          {
            "BasicAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "The roleConfiguration id.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "If-None-Match",
            "in": "header",
            "description": "The ETag of the resource as returned in a previous request. This is used to determine if the resource was modified since the previous request. If it was not, the endpoint will respond with a 304.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. This endpoint now supports only the V2 media type: `application/x.topdesk-role-configuration-v2+json`. The previous V1 media type `application/json` is no longer supported. Please update your clients to use the V2 Accept header.",
            "content": {
              "application/x.topdesk-role-configuration-v2+json": {
                "schema": {
                  "$ref": "#/components/schemas/RoleConfigurationResultDtoV2"
                }
              }
            },
            "headers": {
              "ETag": {
                "schema": {
                  "type": "string"
                },
                "description": "The ETag of the resource, uniquely identifying it."
              }
            }
          },
          "304": {
            "description": "The resource was not modified since the previous request. This is determined using the ETag supplied in the If-None-Match header."
          },
          "401": {
            "description": "Not authenticated or invalid authentication token."
          },
          "403": {
            "description": "No permission to access the data. Permission group read permission is required."
          },
          "404": {
            "description": "RoleConfiguration not found."
          }
        }
      }
    },
    "/reporting/1.0.0/roles": {
      "get": {
        "tags": [ "Reporting" ],
        "summary": "Reporting Roles endpoint returning what permissions are assigned to what users, and what users have what permissions.",
        "description": "The endpoint returns all the roles with their assigned permissions and the linked users.",
        "parameters": [
          {
            "name": "$filter",
            "in": "query",
            "description": "A FIQL string to select which roles should be returned. The supported operators are: \n\n* `eq` - equals\n\n* `ne` - not equals\n\n* `and` - and\n\n* `or` - or<br/> (See [FIQL Queries Tutorial](https://developers.topdesk.com/tutorial.html#query)). <br/><br/>The following fields are available for `$filter` parameter:\n\n* `id` - role id\n\n* `name` - role name\n\n* `archived` - role archived status\n\n* `target` - role type, supported types:\n\n  * `default` - general permission group role\n\n  * `admin` - admin role\n\n  * `saassupervisor` - SaaS supervisor role\n\n* `principals` - list of users linked to the role\n\n* `assignedPermissions`- list of permission ids of the assigned permissions checked for the role",
            "required": false,
            "schema": {
              "type": "string",
              "format": "fiql"
            }
          }],
        "responses": {
          "200": {
            "description": "Success - If the `$filter`-parameter is valid the endpoint returns all the roles that meet the condition in the parameter. If `$filter`-parameter is not valid or not specified in the request then the endpoint returns all the roles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/ReportingRoleDto"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated or invalid authentication token."
          },
          "403": {
            "description": "No permission to access the data. Permission group read permission is required."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BasicAuth": {
        "type": "http",
        "scheme": "basic"
      }
    },
    "schemas": {
      "RoleListEmbedded": {
        "type": "object",
        "properties": {
          "item": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RoleListItemDto"
            }
          }
        }
      },
      "LinkDto": {
        "type": "object",
        "required": [
          "href",
          "type"
        ],
        "properties": {
          "href": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        }
      },
      "RoleListLinks": {
        "type": "object",
        "properties": {
          "self": {
            "$ref": "#/components/schemas/LinkDto"
          }
        }
      },
      "RoleResultLinks": {
        "type": "object",
        "properties": {
          "self": {
            "$ref": "#/components/schemas/LinkDto"
          },
          "archive": {
            "$ref": "#/components/schemas/TypelessLinkDto"
          },
          "unarchive": {
            "$ref": "#/components/schemas/TypelessLinkDto"
          }
        }
      },
      "RoleLinks": {
        "type": "object",
        "properties": {
          "self": {
            "$ref": "#/components/schemas/LinkDto"
          },
          "archive": {
            "$ref": "#/components/schemas/TypelessLinkDto"
          },
          "unarchive": {
            "$ref": "#/components/schemas/TypelessLinkDto"
          }
        }
      },
      "RoleListItemDto": {
        "type": "object",
        "properties": {
          "_links": {
            "$ref": "#/components/schemas/RoleLinks"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "licensed": {
            "type": "boolean",
            "description": "True if the users linked to this role must be paid for. This only applies for the [new pricing model](https://www.topdesk.com/en/pricing/)."
          }
        }
      },
      "RoleListResultDto": {
        "type": "object",
        "properties": {
          "_links": {
            "$ref": "#/components/schemas/RoleListLinks"
          },
          "_embedded": {
            "$ref": "#/components/schemas/RoleListEmbedded"
          }
        }
      },
      "RoleResultDto": {
        "type": "object",
        "properties": {
          "_links": {
            "$ref": "#/components/schemas/RoleResultLinks"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "modifierId": {
            "type": "string",
            "format": "uuid",
            "description": "The principalId of the operator that last modified the role. The corresponding operator can be retrieved from the [operator API](https://developers.topdesk.com/explorer/?page=supporting-files#/Operators/retrieveOperators), using the principalId as a query parameter."
          },
          "creatorId": {
            "type": "string",
            "format": "uuid",
            "description": "The principalId of the operator that last modified the role. The corresponding operator can be retrieved from the [operator API](https://developers.topdesk.com/explorer/?page=supporting-files#/Operators/retrieveOperators), using the principalId as a query parameter."
          },
          "modificationDate": {
            "type": "string",
            "format": "date-time"
          },
          "creationDate": {
            "type": "string",
            "format": "date-time"
          },
          "target": {
            "type": "string",
            "description": "The type of role. This determines which permissions may be set for this role. For the SaaS supervisor role the value is 'saassupervisor', for regular roles, the value is 'default'."
          },
          "licensed": {
            "type": "boolean",
            "description": "True if the users linked to this role must be paid for. This only applies for the [new pricing model](https://www.topdesk.com/en/pricing/)."
          }
        }
      },
      "TypelessLinkDto": {
        "type": "object",
        "required": [
          "href"
        ],
        "properties": {
          "href": {
            "type": "string"
          }
        }
      },
      "RoleConfigurationListResultDto": {
        "type": "object",
        "properties": {
          "_links": {
            "type": "object",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/LinkDto"
              }
            }
          },
          "_embedded": {
            "type": "object",
            "properties": {
              "item": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RoleConfigurationListItemDto"
                }
              }
            }
          }
        }
      },
      "RoleConfigurationListItemDto": {
        "type": "object",
        "properties": {
          "_links": {
            "type": "object",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/LinkDto"
              },
              "from": {
                "description": "Link to the origin corresponding to this roleConfiguration.",
                "allOf": [
                  {"$ref": "#/components/schemas/LinkDto"}
                ]
              },
              "of": {
                "description": "Link to the role corresponding to this roleConfiguration.",
                "allOf": [
                  {"$ref": "#/components/schemas/LinkDto"}
                ]
              }
            }
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "ready": {
            "type": "boolean",
            "description": "Indicates whether this roleConfiguration is currently 'active'. If it is not, saving the role configuration has not fully succeeded yet."
          }
        }
      },
      "RoleConfigurationResultDtoV2": {
        "type": "object",
        "properties": {
          "_links": {
            "type": "object",
            "properties": {
              "self": {
                "$ref": "#/components/schemas/LinkDto"
              },
              "from": {
                "description": "Link to the origin corresponding to this roleConfiguration.",
                "allOf": [
                  {"$ref": "#/components/schemas/LinkDto"}
                ]
              },
              "of": {
                "description": "Link to the role corresponding to this roleConfiguration.",
                "allOf": [
                  {"$ref": "#/components/schemas/LinkDto"}
                ]
              }
            }
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "ready": {
            "type": "boolean",
            "description": "Indicates whether this roleConfiguration is currently 'active'. If it is not, saving the role configuration has not fully succeeded yet."
          },
          "assignedPermissions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AssignedPermissionDtoV2"
            }
          },
          "licensed": {
            "type": "boolean",
            "description": "True if the roleConfiguration contains any permissions that require a license. This only applies for the [new pricing model](https://www.topdesk.com/en/pricing/)."
          }
        }
      },
      "AssignedPermissionDtoV2": {
        "type": "object",
        "properties": {
          "permissionId": {
            "type": "string"
          }
        }
      },
      "ReportingRoleDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "archived": {
            "type": "boolean"
          },
          "target": {
            "type": "string",
            "enum": ["default", "admin", "saassupervisor"]
          },
          "principals": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "assignedPermissions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}