# Copyright (c) Abstract Machines
# SPDX-License-Identifier: Apache-2.0

openapi: 3.0.3
info:
  title: SuperMQ Groups Service
  description: |
    This is the Groups Server based on the OpenAPI 3.0 specification.  It is the HTTP API for managing platform groups. You can now help us improve the API whether it's by making changes to the definition itself or to the code.
    Some useful links:
    - [The SuperMQ repository](https://github.com/absmach/supermq)
  contact:
    email: info@absmach.eu
  license:
    name: Apache 2.0
    url: https://github.com/absmach/supermq/blob/main/LICENSE
  version: 0.18.0

servers:
  - url: http://localhost:9004
  - url: https://localhost:9004

tags:
  - name: Groups
    description: CRUD operations for your groups
    externalDocs:
      description: Find out more about users groups
      url: https://docs.supermq.absmach.eu/
  - name: Roles
    description: All operations involving roles for groups
    externalDocs:
      description: Find out more about roles
      url: https://docs.supermq.absmach.eu/
  - name: Health
    description: Health check operations
    externalDocs:
      description: Find out more about health checks
      url: https://docs.supermq.absmach.eu/

paths:
  /{domainID}/groups:
    post:
      operationId: createGroup
      tags:
        - Groups
      summary: Creates new group
      description: |
        Creates new group that can be used for grouping entities. New account will
        be uniquely identified by its identity.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
      requestBody:
        $ref: "#/components/requestBodies/GroupCreateReq"
      security:
        - bearerAuth: []
      responses:
        "201":
          $ref: "#/components/responses/GroupCreateRes"
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to using an existing identity.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listGroups
      summary: Lists groups.
      description: |
        Lists groups up to a max level of hierarchy that can be fetched in one
        request ( max level = 5). Result can be filtered by metadata. Groups will
        be returned as JSON array or JSON tree. Due to performance concerns, result
        is returned in subsets.
      tags:
        - Groups
      security:
        - bearerAuth: []
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Order"
        - $ref: "#/components/parameters/DirectionOrder"
        - $ref: "#/components/parameters/Level"
        - $ref: "#/components/parameters/Tree"
        - $ref: "#/components/parameters/Tags"
        - $ref: "#/components/parameters/Metadata"
        - $ref: "#/components/parameters/GroupName"
        - $ref: "#/components/parameters/RootGroup"
        - $ref: "#/components/parameters/Status"
        - $ref: "#/components/parameters/ID"
        - $ref: "./schemas/roles.yaml#/components/parameters/ActionsQuery"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleIDQuery"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleNameQuery"
        - $ref: "#/components/parameters/AccessType"
        - $ref: "#/components/parameters/OnlyTotal"
        - $ref: "#/components/parameters/CreatedFrom"
        - $ref: "#/components/parameters/CreatedTo"
      responses:
        "200":
          $ref: "#/components/responses/GroupPageRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Group does not exist.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}:
    get:
      operationId: getGroup
      summary: Gets group info.
      description: |
        Gets info on a group specified by id.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/GroupRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Group does not exist.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    put:
      operationId: updateGroup
      summary: Updates group data.
      description: |
        Updates Name, Description or Metadata of a group.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      security:
        - bearerAuth: []
      requestBody:
        $ref: "#/components/requestBodies/GroupUpdateReq"
      responses:
        "200":
          $ref: "#/components/responses/GroupRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Group does not exist.
        "409":
          description: Failed due to using an existing identity.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"
    delete:
      summary: Delete group for a group with the given id.
      description: |
        Delete group removes a group with the given id from repo
        and removes all the policies related to this group.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Group deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Unauthorized access to group id.
        "404":
          description: A non-existent entity request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/tags:
    patch:
      operationId: updateGroupTags
      summary: Updates group tags.
      description: |
        Update is performed by replacing the current resource data with values
        provided in a request payload. Note that the group's ID will not be
        affected.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      security:
        - bearerAuth: []
      requestBody:
        $ref: "#/components/requestBodies/GroupUpdateTagsReq"
      responses:
        "200":
          $ref: "#/components/responses/GroupRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Group does not exist.
        "409":
          description: Failed due to using an existing identity.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/enable:
    post:
      operationId: enableGroup
      summary: Enables a group
      description: |
        Enables a specific group that is identifier by the group ID.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/GroupRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to already enabled group.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/disable:
    post:
      operationId: disableGroup
      summary: Disables a group
      description: |
        Disables a specific group that is identifier by the group ID.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "#/components/responses/GroupRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to already disabled group.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/hierarchy:
    get:
      operationId: listGroupHierarchy
      summary: Lists groups hierarchy.
      description: |
        Lists groups heirarchy up to a max level of hierarchy that can be fetched in one
        request ( max level = 5). Result can be filtered by metadata. Groups will
        be returned as JSON array or JSON tree. Due to performance concerns, result
        is returned in subsets.
      tags:
        - Groups
      security:
        - bearerAuth: []
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "#/components/parameters/Level"
        - $ref: "#/components/parameters/Tree"
        - $ref: "#/components/parameters/Direction"
        - $ref: "#/components/parameters/CreatedFrom"
        - $ref: "#/components/parameters/CreatedTo"
      responses:
        "200":
          $ref: "#/components/responses/GroupsHierarchyPageRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Group does not exist.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/parent:
    post:
      operationId: setGroupParentGroup
      summary: Sets a parent group for a group.
      description: |
        Sets a parent group for a specific group that is identified by the group ID.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      requestBody:
        $ref: "#/components/requestBodies/GroupParentReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Parent group set.
          content:
            application/json:
              schema:
                type: object
          links: {}
        "400":
          description: Failed due to malformed group's ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    delete:
      operationId: removeGroupParentGroup
      summary: Removes a parent group from a group.
      description: |
        Removes a parent group from a specific group that is identified by the group ID.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      requestBody:
        $ref: "#/components/requestBodies/GroupParentReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Parent group removed.
          content:
            application/json:
              schema:
                type: object
          links: {}
        "400":
          description: Failed due to malformed group's ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/children:
    post:
      operationId: addChildrenGroups
      summary: Add children groups.
      description: |
        Adds children groups for a specific group that is identified by the group ID.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      requestBody:
        $ref: "#/components/requestBodies/GroupChildrenReq"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Children groups added successfully.
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to using an existing identity.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    delete:
      operationId: removeChildrenGroups
      summary: Remove children groups.
      description: |
        Removes children groups for a specific group that is identified by the group ID.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      requestBody:
        $ref: "#/components/requestBodies/GroupChildrenReq"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Children groups removed successfully.
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to using an existing identity.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listChildrenGroups
      summary: List children of a certain group
      description: |
        Lists groups up to a max level of hierarchy that can be fetched in one
        request ( max level = 5). Result can be filtered by metadata. Groups will
        be returned as JSON array or JSON tree. Due to performance concerns, result
        is returned in subsets.
      tags:
        - Groups
      security:
        - bearerAuth: []
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/StartLevel"
        - $ref: "#/components/parameters/EndLevel"
        - $ref: "#/components/parameters/Tree"
        - $ref: "#/components/parameters/Metadata"
        - $ref: "#/components/parameters/GroupName"
      responses:
        "200":
          $ref: "#/components/responses/GroupPageRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: Group does not exist.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/children/all:
    delete:
      operationId: removeAllChildrenGroups
      summary: Remove all children groups.
      description: |
        Removes all children groups for a specific group that is identified by the group ID.
      tags:
        - Groups
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Children groups removed successfully.
        "400":
          description: Failed due to malformed JSON.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "409":
          description: Failed due to using an existing identity.
        "415":
          description: Missing or invalid content type.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles:
    post:
      operationId: createGroupRole
      summary: Creates a role for a group
      description: |
        Creates a role for a specific group that is identified by the group ID.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/CreateRoleReq"
      security:
        - bearerAuth: []
      responses:
        "201":
          $ref: "./schemas/roles.yaml#/components/responses/CreateRoleRes"
        "400":
          description: Failed due to malformed group's ID.
        "401":
          description: Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listGroupRoles
      tags:
        - Roles
      summary: Retrieves groups roles.
      description: |
        Retrieves a list of group roles. Due to performance concerns, data
        is retrieved in subsets. The API groups must ensure that the entire
        dataset is consumed either by making subsequent requests, or by
        increasing the subset size of the initial request.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListRolesRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles/members:
    get:
      operationId: getGroupMembers
      tags:
        - Roles
      summary: Retrieves group members from all roles.
      description: |
        Retrieves members from role for the specific group.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListEntityMembersRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles/{roleID}:
    get:
      operationId: getGroupRole
      tags:
        - Roles
      summary: Retrieves group role.
      description: |
        Retrieves a specific group role that is identified by the role name.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/GetRoleRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    put:
      operationId: updateGroupRole
      summary: Updates group role.
      description: |
        Updates a specific group role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/UpdateRoleReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/GetRoleRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    delete:
      operationId: deleteGroupRole
      summary: Deletes group role.
      description: |
        Deletes a specific group role that is identifier by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Role deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles/{roleID}/actions:
    post:
      operationId: addGroupRoleAction
      summary: Adds a role action for a group role.
      description: |
        Adds a role action for a specific group role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/AddRoleActionsReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/AddRoleActionsRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listGroupRoleActions
      tags:
        - Roles
      summary: Lists group role actions.
      description: |
        Retrieves a list of group role actions.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListRoleActionsRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles/{roleID}/actions/delete:
    post:
      operationId: deleteGroupRoleAction
      summary: Deletes role actions for a group role.
      description: |
        Deletes a role action for a specific group role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/AddRoleActionsReq"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Role actions deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles/{roleID}/actions/delete-all:
    post:
      operationId: deleteAllGroupRoleActions
      summary: Deletes all role actions for a group role.
      description: |
        Deletes all role actions for a specific group role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: All role actions deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles/{roleID}/members:
    post:
      operationId: addGroupRoleMember
      summary: Adds a member to a group role.
      description: |
        Adds a member to a specific group role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/AddRoleMembersReq"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/AddRoleMembersRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

    get:
      operationId: listGroupRoleMembers
      tags:
        - Roles
      summary: Lists group role members.
      description: |
        Retrieves a list of group role members.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListRoleMembersRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles/{roleID}/members/delete:
    post:
      operationId: deleteGroupRoleMembers
      summary: Deletes members from a group role.
      description: |
        Deletes a member from a specific group role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      requestBody:
        $ref: "./schemas/roles.yaml#/components/requestBodies/AddRoleMembersReq"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Role members deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/{groupID}/roles/{roleID}/members/delete-all:
    post:
      operationId: deleteAllGroupRoleMembers
      summary: Deletes all members from a group role.
      description: |
        Deletes all members from a specific group role that is identified by the role name.
      tags:
        - Roles
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
        - $ref: "#/components/parameters/GroupID"
        - $ref: "./schemas/roles.yaml#/components/parameters/RoleID"
      security:
        - bearerAuth: []
      responses:
        "204":
          description: All role members deleted.
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /{domainID}/groups/roles/available-actions:
    get:
      operationId: listAvailableActions
      tags:
        - Roles
      summary: Retrieves available actions.
      description: |
        Retrieves a list of available actions.
      parameters:
        - $ref: "auth.yaml#/components/parameters/DomainID"
      security:
        - bearerAuth: []
      responses:
        "200":
          $ref: "./schemas/roles.yaml#/components/responses/ListAvailableActionsRes"
        "400":
          description: Failed due to malformed query parameters.
        "401":
          description: |
            Missing or invalid access token provided.
        "403":
          description: Failed to perform authorization over the entity.
        "404":
          description: A non-existent entity request.
        "422":
          description: Database can't process request.
        "500":
          $ref: "#/components/responses/ServiceError"

  /health:
    get:
      operationId: health
      summary: Retrieves service health check info.
      tags:
        - Health
      security: []
      responses:
        "200":
          $ref: "#/components/responses/HealthRes"
        "500":
          $ref: "#/components/responses/ServiceError"

components:
  schemas:
    GroupReqObj:
      type: object
      properties:
        name:
          type: string
          example: groupName
          description: Free-form group name. Group name is unique on the given hierarchy level.
        description:
          type: string
          example: long group description
          description: Group description, free form text.
        parent_id:
          type: string
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Id of parent group, it must be existing group.
        metadata:
          type: object
          example: { "domain": "example.com" }
          description: Arbitrary, object-encoded groups's data.
        status:
          type: string
          description: Group Status
          format: string
          example: enabled
      required:
        - name

    Group:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Unique group identifier generated by the service.
        name:
          type: string
          example: groupName
          description: Free-form group name. Group name is unique on the given hierarchy level.
        domain_id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: ID of the domain to which the group belongs..
        parent_id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Group parent identifier.
        description:
          type: string
          example: long group description
          description: Group description, free form text.
        tags:
          type: array
          items:
            type: string
          example: ["tag1", "tag2"]
          description: Group tags.
        metadata:
          type: object
          example: { "role": "general" }
          description: Arbitrary, object-encoded groups's data.
        path:
          type: string
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879.bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Hierarchy path, concatenated ids of group ancestors.
        level:
          type: integer
          description: Level in hierarchy, distance from the root group.
          format: int32
          example: 2
          maximum: 5
        created_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Datetime when the group was created.
        updated_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Datetime when the group was created.
        status:
          type: string
          description: Group Status
          format: string
          example: enabled
      xml:
        name: group

    Members:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: User unique identifier.
        first_name:
          type: string
          example: John
          description: User's first name.
        last_name:
          type: string
          example: Doe
          description: User's last name.
        email:
          type: string
          example: user@supermq.com
          description: User's email address.
        tags:
          type: array
          minItems: 0
          items:
            type: string
          example: ["computations", "datasets"]
          description: User tags.
        credentials:
          type: object
          properties:
            username:
              type: string
              example: john_doe
              description: User's username.
            secret:
              type: string
              example: password
              minimum: 8
              description: User secret password.
        metadata:
          type: object
          example: { "role": "general" }
          description: Arbitrary, object-encoded user's data.
        status:
          type: string
          description: User Status
          format: string
          example: enabled
        created_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the group was created.
        updated_at:
          type: string
          format: date-time
          example: "2019-11-26 13:31:52"
          description: Time when the group was created.
      xml:
        name: members

    GroupsPage:
      type: object
      properties:
        groups:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/Group"
        total:
          type: integer
          example: 1
          description: Total number of items.
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          example: 10
          description: Maximum number of items to return in one page.
      required:
        - total

    GroupsHierarchyPage:
      type: object
      properties:
        level:
          type: integer
          example: 1
          description: Level of hierarchy.
        direction:
          type: integer
          example: -1
          description: Direction of hierarchy traversal.
        groups:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/Group"

    MembersPage:
      type: object
      properties:
        members:
          type: array
          minItems: 0
          uniqueItems: true
          items:
            $ref: "#/components/schemas/Members"
        total:
          type: integer
          example: 1
          description: Total number of items.
        offset:
          type: integer
          description: Number of items to skip during retrieval.
        limit:
          type: integer
          example: 10
          description: Maximum number of items to return in one page.
      required:
        - members
        - total
        - level

    GroupUpdate:
      type: object
      properties:
        name:
          type: string
          example: groupName
          description: Free-form group name. Group name is unique on the given hierarchy level.
        description:
          type: string
          example: long description but not too long
          description: Group description, free form text.
        metadata:
          type: object
          example: { "role": "general" }
          description: Arbitrary, object-encoded groups's data.
      required:
        - name
        - metadata
        - description

    GroupUpdateTags:
      type: object
      properties:
        tags:
          type: array
          minItems: 0
          items:
            type: string
          example: ["tag1", "tag2"]
          description: Group tags.
      required:
        - tags

    ParentGroupReqObj:
      type: object
      properties:
        group_id:
          type: string
          format: uuid
          example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Parent group unique identifier.
      required:
        - group_id

    ChildrenGroupReqObj:
      type: object
      properties:
        groups:
          type: array
          minItems: 1
          items:
            type: string
            format: uuid
            example: bb7edb32-2eac-4aad-aebe-ed96fe073879
          description: Children group IDs.
      required:
        - groups

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
      example: { "error": "malformed entity specification" }

    HealthRes:
      type: object
      properties:
        status:
          type: string
          description: Service status.
          enum:
            - pass
        version:
          type: string
          description: Service version.
          example: 0.0.1
        commit:
          type: string
          description: Service commit hash.
          example: 7d6f4dc4f7f0c1fa3dc24eddfb18bb5073ff4f62
        description:
          type: string
          description: Service description.
          example: <service_name> service
        build_time:
          type: string
          description: Service build time.
          example: 1970-01-01_00:00:00

  parameters:
    Referer:
      name: Referer
      description: Host being sent by browser.
      in: header
      schema:
        type: string
      required: true

    UserID:
      name: userID
      description: Unique user identifier.
      in: path
      schema:
        type: string
        format: uuid
        minLength: 36
        maxLength: 36
        pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
      required: true
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    Status:
      name: status
      description: Lists groups with the given status.
      in: query
      schema:
        type: string
        enum:
          - enabled
          - disabled
          - all
      required: false
      example: enabled

    Tags:
      name: tags
      description: Group tags. Multiple tags can be specified separated by comma for OR condition and plus for AND condition.
      in: query
      schema:
        type: string
      required: false
      example: "orange,yellow"

    GroupName:
      name: name
      description: Group's name.
      in: query
      schema:
        type: string
      required: false
      example: "groupName"

    GroupDescription:
      name: description
      description: Group's description.
      in: query
      schema:
        type: string
      required: false
      example: "group description"

    GroupID:
      name: groupID
      description: Unique group identifier.
      in: path
      schema:
        type: string
        format: uuid
        minLength: 36
        maxLength: 36
        pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
      required: true
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    ChannelID:
      name: channelID
      description: Unique channel identifier.
      in: path
      schema:
        type: string
        format: uuid
        minLength: 36
        maxLength: 36
        pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
      required: true
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    MemberID:
      name: memberID
      description: Unique member identifier.
      in: path
      schema:
        type: string
        format: uuid
        minLength: 36
        maxLength: 36
        pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"
      required: true
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    ParentID:
      name: parentID
      description: Unique parent identifier for a group.
      in: query
      schema:
        type: string
        format: uuid
      required: false
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    Level:
      name: level
      description: Level of hierarchy up to which to retrieve groups from given group id.
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 5
      required: false

    StartLevel:
      name: start_level
      description: Level of hierarchy from which to start retrieving groups from given group id.
      in: query
      schema:
        type: integer
      required: false

    EndLevel:
      name: end_level
      description: Level of hierarchy up to which to retrieve groups from given group id.
      in: query
      schema:
        type: integer
      required: false

    Direction:
      name: direction
      description: Direction of hierarchy traversal.
      in: query
      schema:
        type: integer
      required: false

    Tree:
      name: tree
      description: Specify type of response, JSON array or tree.
      in: query
      required: false
      schema:
        type: boolean
        default: false

    RootGroup:
      name: root_group
      description: List groups without a parent group.
      in: query
      schema:
        type: boolean
        default: false
      required: false

    Metadata:
      name: metadata
      description: Metadata filter. Filtering is performed matching the parameter with metadata on top level. Parameter is json.
      in: query
      schema:
        type: string
      required: false

    Limit:
      name: limit
      description: Size of the subset to retrieve.
      in: query
      schema:
        type: integer
        default: 10
        maximum: 100
        minimum: 1
      required: false
      example: 100

    Offset:
      name: offset
      description: Number of items to skip during retrieval.
      in: query
      schema:
        type: integer
        default: 0
        minimum: 0
      required: false
      example: 0

    Order:
      name: order
      description: Field by which to order the results
      in: query
      schema:
        type: string
      required: false
      example: created_at

    DirectionOrder:
      name: order
      description: Direction of ordering the results.
      in: query
      schema:
        type: string
        enum:
          - asc
          - desc
      required: false
      example: desc

    ID:
      name: id
      description: List groups with the given ID.
      in: query
      schema:
        type: string
        format: uuid
      required: false
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

    AccessType:
      name: access_type
      description: Type of access the user has on the group.
      in: query
      schema:
        type: string
        enum:
          - direct
          - domain
          - indirect
          - indirect_group
      required: false
      example: direct

    OnlyTotal:
      name: only_total
      description: If true, the response will contain only the total number of groups that match the query parameters.
      in: query
      schema:
        type: boolean
        default: false
      required: false

    CreatedFrom:
      name: created_from
      description: Filter groups created from this date (inclusive).
      in: query
      schema:
        type: string
        format: date-time
      required: false
      example: "2023-01-01T00:00:00Z"

    CreatedTo:
      name: created_to
      description: Filter groups created up to this date (inclusive).
      in: query
      schema:
        type: string
        format: date-time
      required: false
      example: "2023-12-31T23:59:59Z"

    User:
      name: user
      description: If provided lists groups associated with a user with the provided ID. Only available for admin users.
      in: query
      schema:
        type: string
        format: uuid
        minLength: 36
      required: false
      example: bb7edb32-2eac-4aad-aebe-ed96fe073879

  requestBodies:
    GroupCreateReq:
      description: JSON-formatted document describing the new group to be registered
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupReqObj"

    GroupUpdateReq:
      description: JSON-formated document describing the metadata and name of group to be update
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupUpdate"

    GroupUpdateTagsReq:
      description: JSON-formated document describing the tags of group to be updated.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupUpdateTags"

    GroupParentReq:
      description: JSON-formated document describing the parent group to be set to or removed from a group.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ParentGroupReqObj"

    GroupChildrenReq:
      description: JSON-formated document describing the children groups to be added to a group.
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ChildrenGroupReqObj"

  responses:
    GroupCreateRes:
      description: Registered new group.
      headers:
        Location:
          schema:
            type: string
            format: url
          description: Registered group relative URL in the format `/groups/<group_id>`
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Group"
      links:
        get:
          operationId: getGroup
          parameters:
            groupID: $response.body#/id
        # get_children:
        #   operationId: listChildrenGroups
        #   parameters:
        #     groupID: $response.body#/id
        update:
          operationId: updateGroup
          parameters:
            groupID: $response.body#/id
        disable:
          operationId: disableGroup
          parameters:
            groupID: $response.body#/id
        enable:
          operationId: enableGroup
          parameters:
            groupID: $response.body#/id

    GroupRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Group"
      links:
        get_children:
          operationId: listChildrenGroups
          parameters:
            groupID: $response.body#/id
        update:
          operationId: updateGroup
          parameters:
            groupID: $response.body#/id
        disable:
          operationId: disableGroup
          parameters:
            groupID: $response.body#/id
        enable:
          operationId: enableGroup
          parameters:
            groupID: $response.body#/id

    GroupPageRes:
      description: Data retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupsPage"
      links: {}

    GroupsHierarchyPageRes:
      description: Group hierarchy retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GroupsHierarchyPage"
      links: {}

    MembersPageRes:
      description: Group members retrieved.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MembersPage"
      links: {}

    HealthRes:
      description: Service Health Check.
      content:
        application/health+json:
          schema:
            $ref: "#/components/schemas/HealthRes"

    ServiceError:
      description: Unexpected server-side error occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        * User access: "Authorization: Bearer <user_access_token>"

    refreshAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        * User refresh token used to get another access token: "Authorization: Bearer <user_refresh_token>"
security:
  - bearerAuth: []
  - refreshAuth: []
