Mend Administration - Groups API

openapi: 3.0.1
info:
  title: Mend Access Management Administration - Groups API
  description: 'Mend''s enhanced API enables automation of workflows in a REST compliant format. The API features:

    + Access for any user with Mend credentials, via a user key available in the user''s profile page in the Mend Platform.

    + Improved security with a JWT token per organization, which expires every 10 minutes.

    + Added scalability with support for cursor pagination and limiting results size.

    + Broader functionality available programmatically.

    + New standard API documentation for easy navigation and search.


    **Note:** To help you get started with the Mend API 3.0, we recommend reviewing our onboarding guide -> [Getting Started with API 3.0](https://docs.mend.io/platform/latest/getting-started-with-mend-api-3-0).

    This resource covers initial setup, authentication instructions, and helpful tips to help you successfully begin working with the Mend API 3.0. If you have a dedicated instance of Mend, contact your Mend representative to access this API on your instance.'
  version: '3.0'
servers:
- url: https://baseUrl
  description: Generated server url
security:
- bearer-key: []
tags:
- name: Administration - Groups
paths:
  /api/v3.0/orgs/{orgUuid}/groups:
    get:
      tags:
      - Administration - Groups
      summary: Get All Organization Groups
      description: Returns a list of all groups within an organization
      operationId: getAllOrganizationGroups
      parameters:
      - name: cursor
        in: query
        description: Parameter indicates the starting point for retrieving results, the first call doesn't include a cursor parameter in the request, the API response includes the first set of results along with a cursor pointing to the last item retrieved.
        allowEmptyValue: true
        schema:
          type: string
      - name: limit
        in: query
        description: Specifies the maximum number of items to be returned in the response.
        allowEmptyValue: true
        schema:
          maximum: 10000
          type: string
          default: '50'
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponsePageableV3ListGroupSummaryDTOV3'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
    post:
      tags:
      - Administration - Groups
      summary: Create Group
      description: Creates a new group for an organization
      operationId: createGroup
      parameters:
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGroupRequestDTO'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponseV3GroupDTO'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
  /api/v3.0/orgs/{orgUuid}/groups/roleDefinitions:
    get:
      tags:
      - Administration - Groups
      summary: Get All Organization Groups with Role Definitions
      description: Returns a list of all groups within an organization with their role definitions
      operationId: getAllOrganizationGroupsWithRoleDefinitions
      parameters:
      - name: cursor
        in: query
        description: Parameter indicates the starting point for retrieving results, the first call doesn't include a cursor parameter in the request, the API response includes the first set of results along with a cursor pointing to the last item retrieved.
        allowEmptyValue: true
        schema:
          type: string
      - name: limit
        in: query
        description: Specifies the maximum number of items to be returned in the response.
        allowEmptyValue: true
        schema:
          maximum: 10000
          type: string
          default: '50'
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponsePageableV3ListGroupWithRoleDefinitionsSummaryDTOV3'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
  /api/v3.0/orgs/{orgUuid}/groups/{groupUuid}:
    get:
      tags:
      - Administration - Groups
      summary: Get Group
      description: Returns the given group of an organization
      operationId: getGroup
      parameters:
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: Group UUID (Administration > Groups)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponseV3GroupDTO'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
    put:
      tags:
      - Administration - Groups
      summary: Update Group
      description: Updates the properties of a given group
      operationId: updateGroup
      parameters:
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: Group UUID (Administration > Groups)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateGroupRequestDTO'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponseV3GroupDTO'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
    delete:
      tags:
      - Administration - Groups
      summary: Delete Group
      description: Deletes the given group
      operationId: deleteGroup
      parameters:
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: Group UUID (Administration > Groups)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponseV3MessageDTO'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
  /api/v3.0/orgs/{orgUuid}/groups/{groupUuid}/roles:
    get:
      tags:
      - Administration - Groups
      summary: Get Group Roles
      description: Returns the list of roles associated with a given group
      operationId: getGroupRoles
      parameters:
      - name: cursor
        in: query
        description: Parameter indicates the starting point for retrieving results, the first call doesn't include a cursor parameter in the request, the API response includes the first set of results along with a cursor pointing to the last item retrieved.
        allowEmptyValue: true
        schema:
          type: string
      - name: limit
        in: query
        description: Specifies the maximum number of items to be returned in the response.
        allowEmptyValue: true
        schema:
          maximum: 10000
          type: string
          default: '50'
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: The group UUID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponsePageableV3ListMultipleGroupRolesPerContextDTOV3'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
    put:
      tags:
      - Administration - Groups
      summary: Remove Group Roles
      description: Deletes a role from a group
      operationId: removeGroupRoles
      parameters:
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: Group UUID (Administration > Groups)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupRoleRequestDTOV3'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponseV3MessageDTO'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
    post:
      tags:
      - Administration - Groups
      summary: Add Group Roles
      description: Creates a new group role for an organization
      operationId: addGroupRoles
      parameters:
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: Group UUID (Administration > Groups)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupRoleRequestDTOV3'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponseV3GroupRoleDTOV3'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
  /api/v3.0/orgs/{orgUuid}/groups/{groupUuid}/users:
    get:
      tags:
      - Administration - Groups
      summary: Get Group Users
      description: Returns a list of users that belong to given group
      operationId: getGroupUsers
      parameters:
      - name: cursor
        in: query
        description: Parameter indicates the starting point for retrieving results, the first call doesn't include a cursor parameter in the request, the API response includes the first set of results along with a cursor pointing to the last item retrieved.
        allowEmptyValue: true
        schema:
          type: string
      - name: limit
        in: query
        description: Specifies the maximum number of items to be returned in the response.
        allowEmptyValue: true
        schema:
          maximum: 10000
          type: string
          default: '50'
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: The group UUID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponsePageableV3ListUserInfoDTO'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
    post:
      tags:
      - Administration - Groups
      summary: Add User to Group
      description: Adds a user to an organization's group
      operationId: addUsersToGroup
      parameters:
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: Group UUID (Administration > Groups)
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserEmailsRequestDTO'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponseV3MessageDTO'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
  /api/v3.0/orgs/{orgUuid}/groups/{groupUuid}/users/{userUuid}:
    delete:
      tags:
      - Administration - Groups
      summary: Remove User From Group
      description: Deletes a user from an organization's group
      operationId: deleteUserFromGroup
      parameters:
      - name: orgUuid
        in: path
        description: 'org UUID (from the Mend App: **Administration** General > **Organization UUID**).'
        required: true
        schema:
          type: string
      - name: groupUuid
        in: path
        description: Group UUID (Administration > Groups)
        required: true
        schema:
          type: string
      - name: userUuid
        in: path
        description: User UUID (Administration > Users)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DWRResponseV3MessageDTO'
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/DWRResponseBase'
components:
  schemas:
    CreateGroupRequestDTO:
      required:
      - description
      - name
      type: object
      properties:
        name:
          title: Group Name
          type: string
          example: Group A
        description:
          title: Group Description
          type: string
          example: Group description
    GroupDTO:
      type: object
      properties:
        uuid:
          title: Group UUID
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        name:
          title: Group Name
          type: string
          example: Group A
        description:
          title: Group Description
          type: string
          example: Group description
        userCount:
          title: User Count
          type: integer
          format: int32
          example: 22
    DWRResponseV3GroupDTO:
      type: object
      properties:
        supportToken:
          title: Support Token
          type: string
          example: 1171c60d
        response:
          $ref: '#/components/schemas/GroupDTO'
    DWRResponsePageableV3ListMultipleGroupRolesPerContextDTOV3:
      type: object
      properties:
        additionalData:
          title: Provides insights into endpoint-supported pagination information.
          type: object
          description: '+ **totalItems**: The total count of data points returned in an API response.

            '
          example:
            totalItems: '422'
            next: http://someUrl?cursor=3
            cursor: 3
        supportToken:
          title: Support Token
          type: string
          example: 1171c60d
        response:
          type: array
          items:
            $ref: '#/components/schemas/MultipleGroupRolesPerContextDTOV3'
    DWRResponseV3GroupRoleDTOV3:
      type: object
      properties:
        supportToken:
          title: Support Token
          type: string
          example: 1171c60d
        response:
          $ref: '#/components/schemas/GroupRoleDTOV3'
    GroupScopeMultiRoleDefinitionDTOV3:
      type: object
      properties:
        scopeUuid:
          type: string
        scopeName:
          type: string
        scopeType:
          type: string
          enum:
          - organization
          - application
          - project
          - account
          - unsupported
        roleDefinitions:
          type: array
          items:
            $ref: '#/components/schemas/RoleDefinitionDTOV3'
    GroupWithRoleDefinitionsSummaryDTOV3:
      type: object
      properties:
        uuid:
          title: Group UUID
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        name:
          title: Group Name
          type: string
          example: Group A
        description:
          title: Group Description
          type: string
          example: Group description
        users:
          title: User Count
          type: integer
          description: The amount of users in that group
          format: int32
          example: 22
        affectedApplications:
          title: Affected Applications
          type: integer
          format: int32
          example: 5
        roleDefinitions:
          type: array
          items:
            $ref: '#/components/schemas/GroupScopeMultiRoleDefinitionDTOV3'
    MessageDTO:
      type: object
      properties:
        message:
          title: message
          type: string
          example: Success!
    UserEmailsRequestDTO:
      required:
      - userEmails
      type: object
      properties:
        userEmails:
          uniqueItems: true
          type: array
          items:
            type: string
            example: jon.smith@mail.com
    RoleDefinitionDTOV3:
      type: object
      properties:
        uuid:
          type: string
        name:
          type: string
        description:
          type: string
        type:
          type: string
        scopeType:
          type: string
          enum:
          - organization
          - application
          - project
          - account
          - unsupported
        createdBy:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        originalRole:
          type: string
        capabilities:
          type: array
          items:
            type: string
    UpdateGroupRequestDTO:
      type: object
      properties:
        name:
          title: Group Name
          type: string
          example: Group A
        description:
          title: Group Description
          type: string
          example: Group description
      description: DTO for updating an existing group
    DWRResponsePageableV3ListGroupSummaryDTOV3:
      type: object
      properties:
        additionalData:
          title: Provides insights into endpoint-supported pagination information.
          type: object
          description: '+ **totalItems**: The total count of data points returned in an API response.

            '
          example:
            totalItems: '422'
            next: http://someUrl?cursor=3
            cursor: 3
        supportToken:
          title: Support Token
          type: string
          example: 1171c60d
        response:
          type: array
          items:
            $ref: '#/components/schemas/GroupSummaryDTOV3'
    DWRResponseBase:
      type: object
      properties:
        supportToken:
          title: Support Token
          type: string
          example: 1171c60d
    DWRResponsePageableV3ListGroupWithRoleDefinitionsSummaryDTOV3:
      type: object
      properties:
        additionalData:
          title: Provides insights into endpoint-supported pagination information.
          type: object
          description: '+ **totalItems**: The total count of data points returned in an API response.

            '
          example:
            totalItems: '422'
            next: http://someUrl?cursor=3
            cursor: 3
        supportToken:
          title: Support Token
          type: string
          example: 1171c60d
        response:
          type: array
          items:
            $ref: '#/components/schemas/GroupWithRoleDefinitionsSummaryDTOV3'
    GroupSummaryDTOV3:
      type: object
      properties:
        uuid:
          title: Group UUID
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        name:
          title: Group Name
          type: string
          example: Group A
        description:
          title: Group Description
          type: string
          example: Group description
        users:
          title: User Count
          type: integer
          description: The amount of users in that group
          format: int32
          example: 22
        affectedApplications:
          title: Affected Applications
          type: integer
          format: int32
          example: 5
        roles:
          type: array
          items:
            $ref: '#/components/schemas/GroupRoleDTOV3'
    UserInfoDTO:
      required:
      - uuid
      type: object
      properties:
        uuid:
          title: User UUID
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        name:
          title: User Name
          type: string
          example: Jon Smith
        email:
          title: User Email
          type: string
          example: jon.smith@mail.com
        userType:
          title: Type Of User
          type: string
          example: REGULAR
          enum:
          - REGULAR
          - SERVICE
          - SCAN_SUMMARY_RECEIVER
        accountStatus:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - LOCKOUT
    GroupRoleRequestDTOV3:
      required:
      - scopeType
      - scopeUuid
      type: object
      properties:
        scopeUuid:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        scopeType:
          type: string
          example: organization
          enum:
          - organization
          - application
          - project
          - account
          - unsupported
        role:
          type: string
          enum:
          - ADMIN
          - SCAN_MANAGER
          - SECURITY_ANALYST
          - MEMBER
    MultipleGroupRolesPerContextDTOV3:
      required:
      - scopeType
      - scopeUuid
      type: object
      properties:
        scopeUuid:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        scopeName:
          title: Scope Name
          type: string
          example: My Product
        scopeType:
          type: string
          description: Type of entity the role will be associated with
          example: organization
          enum:
          - organization
          - application
          - project
          - account
          - unsupported
        roles:
          type: array
          items:
            title: Role
            type: string
            example: ADMIN
            enum:
            - ADMIN
            - SCAN_MANAGER
            - SECURITY_ANALYST
            - MEMBER
    GroupRoleDTOV3:
      type: object
      properties:
        scopeUuid:
          type: string
          example: 123e4567-e89b-12d3-a456-426655440000
        scopeName:
          title: Context Name
          type: string
          example: My Project
        scopeType:
          type: string
          description: Type of entity the role will be associated with
          example: organization
          enum:
          - organization
          - application
          - project
          - account
          - unsupported
        role:
          type: string
          enum:
          - ADMIN
          - SCAN_MANAGER
          - SECURITY_ANALYST
          - MEMBER
    DWRResponsePageableV3ListUserInfoDTO:
      type: object
      properties:
        additionalData:
          title: Provides insights into endpoint-supported pagination information.
          type: object
          description: '+ **totalItems**: The total count of data points returned in an API response.

            '
          example:
            totalItems: '422'
            next: http://someUrl?cursor=3
            cursor: 3
        supportToken:
          title: Support Token
          type: string
          example: 1171c60d
        response:
          type: array
          items:
            $ref: '#/components/schemas/UserInfoDTO'
    DWRResponseV3MessageDTO:
      type: object
      properties:
        supportToken:
          title: Support Token
          type: string
          example: 1171c60d
        response:
          $ref: '#/components/schemas/MessageDTO'
  securitySchemes:
    bearer-key:
      type: http
      description: JWT token Bearer
      scheme: bearer
      bearerFormat: JWT