openapi: 3.0.0
info:
  title: Group
  description: Group API for ManageEngine ID360
  version: 1.0.0
servers:
  - url: 'https://id360.manageengine.com/api/v1'
    description: 'API Endpoint'
tags:
  - name: group
    description: Group Endpoints
paths:
  /groups :
    get:
      tags:
        - group
      summary: List Groups
      description: The List Groups API can be used to get a list of all groups in your account.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/groupResources'
                  meta:
                    $ref: '#/components/schemas/meta'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invalidParam'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.group.READ
            - id360.group.ALL
    post:
      tags:
        - group
      summary: Create Group
      description: The Create Group API can be used to create a new group in your account.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/groupResource'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/groupResource'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.group.CREATE
            - id360.group.WRITE
            - id360.group.ALL
  /groups/{id}:
    get:
      tags:
        - group
      summary: Get Group
      description: The Get Group API can be used to fetch the details of a specific group in your account.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/groupId'
        - $ref: '#/components/parameters/fields'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/groupResource'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invalidParam'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.group.READ
            - id360.group.ALL
    patch:
      tags:
        - group
      summary: Update Group
      description: The Update Group API can be used to update the details of a specific group in your account.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/groupId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/groupResource'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/groupResource'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.group.UPDATE
            - id360.group.WRITE
            - id360.group.ALL
    delete:
      tags:
        - group
      summary: Delete Group
      description: 'The Delete Group API can be used to delete a specific group in your account.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/groupId'
      responses:
        '204':
          description: No Content
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.group.DELETE
            - id360.group.WRITE
            - id360.group.ALL
components:
  parameters:
    authorization:
      name: Authorization
      in: header
      schema:
        type: string
      description: 'Authorization OAuth token for the API'
      required: true
      example: 'Zoho-oauthtoken 1000.41d**************125f'
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'Accept header for the API'
      required: false
      example: 'application/json'
    groupId:
      in: path
      name: id
      schema:
        type: integer
        example: 2000000000001
      description: 'The ID of the Group to be fetched or updated'
      required: true
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 200
        minimum: 1
        default: 200
      description: 'Limit the number of users to be fetched'
      required: false
      example: 50
    fields:
      in: query
      name: fields
      schema:
        type: string
      description: 'Select the fields to be fetched in the response.'
      required: false
      example: 'id,firstName,email'
    filter:
      in: query
      name: filter
      schema:
        type: string
      description: >
        Filter users based on a the provided SCIM filter query. Refer to filter section for more details
        <br>
        <strong>eg:</strong> firstName eq "John" and lastName eq "Doe"
      required: false
      example: firstName eq "John" and lastName eq "Doe"
    sort:
      in: query
      name: sort
      schema:
        type: string
      description: >
        Sort the users based on the provided field. The default sort order is ascending. To sort in descending order, prefix the field with a - (hyphen).
        <br>
        <strong>eg:</strong> firstName,-lastName
      required: false
      example: 'firstName,-lastName'
    cursor:
      in: query
      name: cursor
      schema:
        type: string
      description: 'Cursor for pagination. Use the next_cursor value from the previous response to fetch the next set of results.'
      required: false
      example: '2000000000001'
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/groupResource'
    groupResources:
      type: array
      description: 'List of groups in the account.'
      items:
        $ref: '#/components/schemas/groupResource'
      example:
        - id: '2000000106686'
          name: 'Group 1'
          description: 'Default group for all users'
          members_count: 5
          when_created: '2024-05-07T10:36:27+05:30'
          is_dynamic: false
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
          members:
            - '2000000108825'
            - '2000000108623'
            - '2000000108895'
            - '2000000105735'
            - '2000000108791'
        - id: '2000000106687'
          name: 'Group 2'
          description: 'Group for Test Team'
          members_count: 3
          when_created: '2024-05-08T11:00:00+05:30'
          is_dynamic: true
          primary_source:
            id: '2000000072638'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018008'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
          members:
            - '2000000108826'
            - '2000000108624'
            - '2000000108896'
    groupResource:
      type: object
      properties:
        id:
          type: string
          description: 'The unique identifier for the group, assigned by the system.'
          example: '2000000106686'
          readOnly: true
        name:
          type: string
          description: 'The name of the group.'
          example: 'Group'
        description:
          type: string
          description: 'A brief description of the group.'
          example: 'Default group for all users'
        members_count:
          type: integer
          description: 'The number of members in the group.'
          example: 5
          readOnly: true
        when_created:
          type: string
          format: date-time
          description: 'The timestamp when the group was created, in ISO 8601 format.'
          example: '2024-05-07T10:36:27+05:30'
          readOnly: true
        is_dynamic:
          type: boolean
          description: 'Indicates whether the group is dynamic or static.'
          example: false
        primary_source:
          $ref: '#/components/schemas/primarySource'
          readOnly: true
        members:
          type: array
          description: 'List of members in the group.'
          items:
            type: string
          writeOnly: true
          example:
            - '2000000108825'
            - '2000000108623'
            - '2000000108895'
            - '2000000105735'
            - '2000000108791'
    primarySource:
      type: object
      description: Details about the primary directory of the group.
      readOnly: true
      properties:
        id:
          type: string
          description: 'The unique identifier for the directory.'
          example: '2000000072637'
        name:
          type: string
          description: 'The name of the application or directory.'
          example: 'Berge-Corp'
        application_service:
          type: object
          description: 'Details about the service associated with the directory or app.'
          properties:
            id:
              type: string
              description: 'The unique identifier for the application service.'
              example: '2000000018007'
            display_name:
              type: string
              description: 'Application Service Name'
              example: 'Universal Directory'
            name:
              type: string
              description: 'Service Name'
              example: 'ZOHO_DIRECTORY'
            logo:
              type: string
              description: 'Application Service Logo'
              example: 'universal-directory'

    memberResources:
      type: array
      description: 'List of members in the group.'
      items:
        $ref: '#/components/schemas/memberResource'
      example:
        - id: '2000000108825'
          display_name: 'John Doe'
          email: 'johndoe@email.com'
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
        - id: '2000000108623'
          display_name: 'Jane Smith'
          email: 'janesmith@email.com'
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
    memberResource:
      type: object
      properties:
        id:
          type: string
          description: 'The unique identifier for the user, assigned by the system.'
          example: '2000000108825'
          readOnly: true
        display_name:
          type: string
          description: 'The display name of the user.'
          example: 'John Doe'
          readOnly: true
        email:
          type: string
          description: 'The email address of the user.'
          example: 'johndoe@email.com'
          readOnly: true
        primary_source:
          $ref: '#/components/schemas/primarySource'
          readOnly: true

    meta:
      type: object
      properties:
        cursor:
          type: string
          example: null
          description: 'Current cursor specified in the request'
        next_cursor:
          type: string
          example: null
          description: 'Next cursor to be used in the next request'
        is_last:
          type: boolean
          example: true
          description: 'Is this the last page of the response'
        limit:
          type: integer
          example: 100
          description: 'Number of users requested to be in the response'
        total_no_of_objects:
          type: integer
          example: 2
          description: 'Total number of users'

    invalidParam:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000107'
            title:
              type: string
              example: 'Invalid Parameter'
            detail:
              type: string
              example: 'The parameter select is invalid.'
    groupNotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '*****'
            title:
              type: string
              example: 'Resource Not Found'
            detail:
              type: string
              example: 'This Group does not exist.'
    unauthorized:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000101'
            title:
              type: string
              example: 'Unauthorized'
            detail:
              type: string
              example: 'The OAuth token is invalid.'
    serverError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000000'
            title:
              type: string
              example: 'Internal Server Error'
            detail:
              type: string
              example: 'An unexpected internal error has occurred on the server. Please try again later.'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      x-authorization-example: 'Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'
      flows:
        clientCredentials:
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            idmpod.group.read: 'Read Group in the account'
            idmpod.group.write: 'Create/Update/Delete Group in the account'
            idmpod.group.create: 'Create Group in the account'
            idmpod.group.delete: 'Delete Group in the account'
            idmpod.group.update: 'Update Group in the account'
            idmpod.group.all: 'Perfrom all actions on Group in the account'