openapi: 3.2.0
info:
  title: Rose Rocket Platform Model User Groups API
  version: 1.0.0
  description: ''
servers:
- url: https://example-org.roserocket.com/api/v2/platformModel
  description: Your organization's hostname with customized subdomain, e.g. "example-org".
- url: https://roserocket.com/api/v2/platformModel
  description: Generic hostname without a customized subdomain.
tags:
- name: User Groups
paths:
  /userGroups:
    get:
      tags:
      - User Groups
      summary: List user groups
      description: Retrieves a list of all user groups belonging to the org.
      operationId: listUserGroups
      responses:
        '200':
          description: List was successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserGroup'
        '401':
          $ref: '#/components/responses/GroupUnauthorized'
        '403':
          $ref: '#/components/responses/GroupForbiddenResponse'
    post:
      tags:
      - User Groups
      summary: Create user group
      description: Creates a new user group and returns the result.
      operationId: createUserGroup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrUpdateUserGroup'
      responses:
        '200':
          description: New user group was successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          $ref: '#/components/responses/GroupValidationError'
        '401':
          $ref: '#/components/responses/GroupUnauthorized'
        '403':
          $ref: '#/components/responses/GroupForbiddenResponse'
        '409':
          $ref: '#/components/responses/GroupNameConflict'
  /userGroups/{groupId}/members:
    get:
      tags:
      - User Groups
      summary: List group members
      description: Lists the users belonging to the indicated group.
      operationId: listUserGroupMembers
      parameters:
      - $ref: '#/components/parameters/GroupId'
      responses:
        '200':
          description: List of group members was successfully returned.
          content:
            application/json:
              schema:
                type: object
                required:
                - userIds
                properties:
                  members:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: ID of the user.
                        addedAt:
                          type: string
                          format: date-time
                          description: Date/time the user was added to the group.
                        addedBy:
                          type: string
                          description: Name of the user who added the user to the group.
        '401':
          $ref: '#/components/responses/GroupUnauthorized'
        '403':
          $ref: '#/components/responses/GroupForbiddenResponse'
        '404':
          $ref: '#/components/responses/GroupNotFound'
    post:
      tags:
      - User Groups
      summary: Add or remove group members
      description: 'Adds or removes users to/from the indicated user group.


        **NOTE:** Removal takes prescendence over addition so if a user ID appears on both the `add` and `remove` collection,

        then that user will *NOT* be a member of the user group after the operation completes.

        '
      operationId: addUserGroupMembers
      parameters:
      - $ref: '#/components/parameters/GroupId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                add:
                  type: array
                  items:
                    type: string
                    format: uuid
                    description: ID of the user to add to the user group.
                remove:
                  type: array
                  items:
                    type: string
                    format: uuid
                    description: ID of the user to remove from the user group.
      responses:
        '200':
          description: User group memberships were successfully updated.
          content:
            application/json:
              schema:
                type: object
                required:
                - added
                - removed
                properties:
                  added:
                    type: number
                    format: int32
                    example: 12
                    description: Number of users added to the user group.
                  removed:
                    type: number
                    format: int32
                    example: 4
                    description: Number of users removed from the user group.
        '401':
          $ref: '#/components/responses/GroupUnauthorized'
        '403':
          $ref: '#/components/responses/GroupForbiddenResponse'
        '404':
          $ref: '#/components/responses/GroupNotFound'
  /userGroups/search:
    post:
      tags:
      - User Groups
      summary: Search user groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchGroupsDTO'
      responses:
        '200':
          description: Search results were successfully retrieved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: number
                    description: The total number of groups
                  results:
                    type: array
                    description: The requested page of results
                    items:
                      $ref: '#/components/schemas/UserGroup'
        '401':
          $ref: '#/components/responses/GroupUnauthorized'
        '403':
          $ref: '#/components/responses/GroupForbiddenResponse'
components:
  responses:
    GroupNameConflict:
      description: The group could not be created or renamed because a group already exists with the name provided.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: number
                example: 409
              message:
                type: string
                example: Group name is already in use.
              error:
                type: string
                example: Conflict
    GroupUnauthorized:
      description: The action could not be completed because the call was not made with a valid JWT identifying the calling user or application.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: number
                example: 401
              message:
                type: string
                example: Action is unauthorized.
              error:
                type: string
                example: Unauthorized
    GroupNotFound:
      description: The operation could not be completed because the requested groupId could not be found.
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: number
                example: 404
              message:
                type: string
                example: User group with ID "XXXXX" not found.
              error:
                type: string
                example: Not Found
    GroupForbiddenResponse:
      description: 'The action could not be performed on the indicated user group(s) because the caller does not have sufficient permission.

        Users require the `userGroupResource` permission scope.

        * Viewer-level permission is required for listing, fetching, and viewing membership of user groups.

        * Editor-level permission is required for updating, deleting, and modifying membership of user groups.

        '
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: number
                example: 403
              message:
                type: string
                example: Action is forbidden.
              error:
                type: string
                example: Forbidden
    GroupValidationError:
      description: The new group could not be created because there was a problem validating the request body.
      content:
        application/json:
          schema:
            type: object
            required:
            - statusCode
            - message
            - error
            properties:
              statusCode:
                type: number
                example: 400
              message:
                type: array
                items:
                  type: string
                  example: name should not be empty
              error:
                type: string
                example: Bad Request
  schemas:
    CreateOrUpdateUserGroup:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the user group as it will appear in the UI.
          example: Admins
        description:
          type: string
          example: Has administrative access to the org
          description: An optional text description of the user group.
    SearchGroupsDTO:
      type: object
      properties:
        name:
          type: string
          description: Name of the user group(s).
          example: Admins
        ids:
          type: array
          items:
            type: string
        limit:
          type: number
        offset:
          type: number
    UserGroup:
      type: object
      required:
      - id
      - name
      - type
      properties:
        id:
          type: string
          format: uuid
          description: The globally-unique ID that identifies the user group.
        name:
          type: string
          description: Name of the user group as it will appear in the UI.
          example: Admins
        type:
          type: string
          description: The type of user group. (I.e. local, Active Directory, etc.)
          enum:
          - local
        description:
          type: string
          example: Has administrative access to the org
          description: An optional text description of the user group.
  parameters:
    GroupId:
      name: groupId
      in: path
      description: The ID of the user group.
      required: true
      schema:
        type: string
        format: uuid
x-readme:
  explorer-enabled: true
  proxy-enabled: true