openapi: 3.0.1
info:
  title: Groups API
  description: Provides access to the groups that are part of a Hyperproof organization.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/groups
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/groups
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/groups
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    post:
      summary: Add Group
      description: >
        `POST /`


        #### Description


        Creates a new group in Hyperproof, defining its name, description, and
        initial membership or permissions.
      operationId: add-group
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupPost'
            example:
              name: Compliance Managers
              groupLeadId: abcdef12-3456-7890-abcd-ef1234567890
              userIds:
                - 195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
                - 12345678-1234-5678-1234-123456789012
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              example:
                id: abcdef12-3456-7890-abcd-ef1234567890
                orgId: 12345678-1234-5678-1234-123456789012
                name: Compliance Managers
                groupLeadId: 876654321-1234-5678-8765-123456789012
                createdOn: '2023-01-01T00:00:00.0000000+00:00'
                updatedOn: '2023-01-01T00:00:00.0000000+00:00'
    get:
      summary: Get Groups
      description: >+
        `GET /`


        #### Description


        Retrieves details of all groups within an organiztion, including their
        names, descriptions, and membership information.

      operationId: get-groups
      parameters:
        - name: status
          in: query
          description: >-
            Comma-separated list of statuses (only active by default). Supported
            values are active and archived.
          schema:
            type: string
        - name: expand
          in: query
          description: >-
            Comma separated list of fields to expand.  Supported values:
            userIds.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupCollection'
              example:
                - id: abcdef12-3456-7890-abcd-ef1234567890
                  orgId: 12345678-1234-5678-1234-123456789012
                  name: Compliance Managers
                  groupLeadId: 876654321-1234-5678-8765-123456789012
                  createdOn: '2023-01-01T00:00:00.0000000+00:00'
                  updatedOn: '2023-01-01T00:00:00.0000000+00:00'
  /{groupId}:
    get:
      summary: Get Group
      description: >
        `GET /{groupId}`


        #### Description


        Retrieves details of a specific group by its unique ID, including its
        name, description, and membership information.
      operationId: get-group
      parameters:
        - name: groupId
          in: path
          description: Unique ID of the group to retrieve.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              example:
                id: abcdef12-3456-7890-abcd-ef1234567890
                orgId: 12345678-1234-5678-1234-123456789012
                name: Compliance Managers
                groupLeadId: 876654321-1234-5678-8765-123456789012
                createdOn: '2023-01-01T00:00:00.0000000+00:00'
                updatedOn: '2023-01-01T00:00:00.0000000+00:00'
    patch:
      summary: Update Group
      description: >
        `PATCH /{groupId}`


        #### Description


        Updates the details of an existing group, allowing changes to its name,
        description, or membership configuration.
      operationId: update-group
      parameters:
        - name: groupId
          in: path
          description: Unique ID of the group to update.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupPatch'
            example:
              name: Compliance Managers
              groupLeadId: abcdef12-3456-7890-abcd-ef1234567890
              clearGroupLead: false
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
              example:
                id: abcdef12-3456-7890-abcd-ef1234567890
                orgId: 12345678-1234-5678-1234-123456789012
                name: Compliance Managers
                groupLeadId: 876654321-1234-5678-8765-123456789012
                createdOn: '2023-01-01T00:00:00.0000000+00:00'
                updatedOn: '2023-01-01T00:00:00.0000000+00:00'
  /users:
    get:
      summary: Get All Group Members
      description: |-
        `GET /users}`

        #### Description

        Retrieves the members of groups in the organization.

        #### Notes and caveats
      operationId: get-all-group-members
      parameters:
        - name: status
          in: query
          description: >-
            Comma-separated list of statuses (only active by default). Supported
            values are active and archived.
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMembersCollection'
              example:
                - id: abcdef12-3456-7890-abcd-ef1234567890
                  groupId: 12345678-1234-5678-1234-123456789012
                  userIds:
                    - 195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
                    - 12345678-1234-5678-1234-123456789012
  /{groupId}/users:
    get:
      summary: Get Group Members
      description: |
        `GET /{groupId}`

        #### Description

        Retrieves the members of a group.
      operationId: get-group-members
      parameters:
        - name: groupId
          in: path
          description: Unique ID of the group.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMembers'
              example:
                id: abcdef12-3456-7890-abcd-ef1234567890
                groupId: 12345678-1234-5678-1234-123456789012
                userIds:
                  - 195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
                  - 12345678-1234-5678-1234-123456789012
    post:
      summary: Add Group Member
      description: >
        `POST /{groupId}/users`


        #### Description


        Adds a user to a specified group, granting them the roles and
        permissions associated with that group.
      operationId: add-group-member
      parameters:
        - name: groupId
          in: path
          description: Unique ID of the group.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMembershipUpdate'
            example:
              userIds:
                - >-
                  195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
                  12345678-1234-5678-1234-123456789012
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMembers'
              example:
                id: abcdef12-3456-7890-abcd-ef1234567890
                groupId: 12345678-1234-5678-1234-123456789012
                userIds:
                  - 195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
                  - 12345678-1234-5678-1234-123456789012
  /{groupId}/users/delete:
    put:
      summary: Remove Group Members
      description: >
        `PUT /{groupId}/users/delete`


        #### Description


        Removes one or more members from a specified group, updating the group’s
        membership and associated permissions.
      operationId: remove-group-member
      parameters:
        - name: groupId
          in: path
          description: Unique ID of the group.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GroupMembershipUpdate'
            example:
              userIds:
                - >-
                  195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
                  12345678-1234-5678-1234-123456789012
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMembers'
              example:
                id: abcdef12-3456-7890-abcd-ef1234567890
                groupId: 12345678-1234-5678-1234-123456789012
                userIds:
                  - 195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
                  - 12345678-1234-5678-1234-123456789012
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            group.read: Grants read access to groups
            group.update: Grants update access to groups
  schemas:
    Group:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the group.
        orgId:
          type: string
          format: uuid
          description: The unique identifier for the organization the group belongs to.
        name:
          type: string
          description: The name of the group.
        groupLeadId:
          type: string
          format: uuid
          description: >-
            The unique identifier of the user who is designated as the group
            lead.
        userIds:
          type: array
          description: The list of unique identifiers of users who are in the group.
          items:
            type: string
        createdOn:
          type: string
          format: date-time
          description: The date and time the group was created (ISO-8601 format).
        updatedOn:
          type: string
          format: date-time
          description: The date and time the group was last updated (ISO-8601 format).
      example:
        id: abcdef12-3456-7890-abcd-ef1234567890
        orgId: 12345678-1234-5678-1234-123456789012
        name: Compliance Managers
        groupLeadId: 876654321-1234-5678-8765-123456789012
        createdOn: '2023-01-01T00:00:00Z'
        updatedOn: '2023-01-01T00:00:00Z'
    GroupCollection:
      type: array
      items:
        type: object
        $ref: '#/components/schemas/Group'
    GroupPatch:
      type: object
      properties:
        name:
          type: string
          description: The name of the group.
        groupLeadId:
          type: string
          format: uuid
          description: >-
            The unique identifier of the user who is designated as the group
            lead.
        clearGroupLead:
          type: boolean
          description: >-
            Clears the group lead if 'true'. If set, groupLeadId must not be
            set.
      example:
        name: Compliance Managers
        groupLeadId: abcdef12-3456-7890-abcd-ef1234567890
        clearGroupLead: false
    GroupPost:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The name of the group.
        groupLeadId:
          type: string
          format: uuid
          description: >-
            The unique identifier of the user who is designated as the group
            lead.
        userIds:
          type: array
          description: The list of unique identifiers of users who are in the group.
          items:
            type: string
      example:
        name: Compliance Managers
        groupLeadId: abcdef12-3456-7890-abcd-ef1234567890
        userIds:
          - 195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
          - 12345678-1234-5678-1234-123456789012
    GroupMembers:
      type: object
      properties:
        groupId:
          type: string
          format: uuid
          description: The unique identifier of the group.
        userIds:
          type: array
          description: The list of unique identifiers of users who are in the group.
          items:
            type: string
      example:
        id: abcdef12-3456-7890-abcd-ef1234567890
        groupId: 12345678-1234-5678-1234-123456789012
        userIds:
          - 195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
          - 12345678-1234-5678-1234-123456789012
    GroupMembersCollection:
      type: array
      items:
        type: object
        $ref: '#/components/schemas/GroupMembers'
    GroupMembershipUpdate:
      type: object
      properties:
        userIds:
          type: array
          items:
            type: string
      example:
        userIds:
          - >-
            195032c4-0a2b-4f3e-8d5f-1a2b3c4d5e6f
            12345678-1234-5678-1234-123456789012
