openapi: 3.0.0
info:
  title: Admin Setting
  description: This is the documentation for the Admin Setting API of Conditional Access Policy in ID360.
  version: 1.0.0
servers:
  - url: 'https://id360.manageengine.com/api/v1'
    description: 'API Endpoint'
tags:
  - name: cap-admin-setting
    description: CAP Admin Setting Endpoint
paths:
  # Conditional Access Policy Admin Settings
  /protection/admin-settings:
    get:
      tags:
        - cap-admin-setting
      summary: Get Admin Settings
      description: Retrieves the admin settings for the ID360 application.
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/adminSettingsResource'
        '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.conditional_access_policy.read
            - id360.conditional_access_policy.all
    patch:
      tags:
        - cap-admin-setting
      summary: Update Admin Settings
      description: Updates the admin settings for the ID360 application.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/adminSettingsResource'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/adminSettingsResource'
        '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.conditional_access_policy.create
            - id360.conditional_access_policy.write
            - id360.conditional_access_policy.all

  /protection/admin-settings/offline-protected-devices:
    get:
      tags:
        - cap-admin-setting
      summary: List Offline Protection Devices
      description: Retrieve a list of offline protection devices
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/devices'
                  meta:
                    $ref: '#/components/schemas/meta'
        '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.conditional_access_policy.read
            - id360.conditional_access_policy.all'

  /protection/admin-settings/offline-protected-device-groups:
    get:
      tags:
        - cap-admin-setting
      summary: List Offline Protection Groups
      description: Retrieve a list of offline protection groups
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/filter'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/groups'
                  meta:
                    $ref: '#/components/schemas/meta'
        '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.conditional_access_policy.read
            - id360.conditional_access_policy.all'
components:
  parameters:
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'Accept header for the API'
      required: false
      example: 'application/json'
    from:
      in: query
      name: from
      schema:
        type: integer
        default: 1
      description: >
        Start index for pagination.
      required: false
      example: 1
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 100
        minimum: 1
        default: 25
      description: >
        Maximum number of records to return in the response.
        <br>
        <strong>eg:</strong> 50
      required: false
      example: 50
    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> name eq "Policy 01"
      required: false
      example: name eq "Policy 01"
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/adminSettingsResource'
    # Admin Setting Schemas
    adminSettingsResource:
      type: object
      properties:
        passwordless_enabled_for_nps_vpn:
          type: boolean
          description: Indicates if passwordless login is enabled for NPS VPN.
          example: true
        captcha_type:
          type: string
          description: Type of CAPTCHA used for login.
          enum:
            - 'recaptcha'
            - 'text_captcha'
          example: 'recaptcha'
        account_blocking_settings:
          type: object
          properties:
            failed_attempts_threshold:
              type: integer
              description: Maximum number of failed login attempts before blocking.
              example: 5
            failed_attempts_reset_interval:
              type: integer
              description: Time interval in minutes for counting failed attempts.
              example: 30
            is_block_forever:
              type: boolean
              description: Indicates if the account should be blocked indefinitely after exceeding the threshold.
              example: false
            blocking_duration:
              type: integer
              description: Duration in minutes for which the account will be blocked if is_block_forever is false.
              example: 30
            reset_failure_attempts_on_success:
              type: boolean
              description: Indicates if failure attempts should be reset upon successful login.
              example: true
        offline_mfa_settings:
          type: object
          properties:
            is_enabled:
              type: boolean
              description: Indicates if offline MFA is enabled.
              example: true
            devices_assignment:
              type: object
              properties:
                device_ids:
                  type: array
                  items:
                    type: string
                  description: List of device IDs assigned to the policy.
                  example:
                    - '2000000092642'
                    - '2000000092643'
                group_ids:
                  type: array
                  items:
                    type: string
                  description: List of group IDs assigned to the policy.
                  example:
                    - '2000000092616'
                    - '2000000092617'
                all_devices_group_selected:
                  type: boolean
                  description: Indicates if all devices group is selected for the policy.
                  example: false
            actions:
              type: array
              items:
                type: string
              description: >
                List of action methods allowed, available actions are:
                <br>
                <ul>
                  <li>InteractiveLogon </li>
                  <li>MachineUnlock</li>
                  <li>RDP</li>
                  <li>SSH</li>
                  <li>UAC</li>
                  <li>Sudo</li>
                </ul>
              example:
                - 'InteractiveLogon'
                - 'RDP'
            secondary_authentication:
              $ref: '#/components/schemas/secondaryFactor'
            offline_access_allowed_duration:
              type: object
              description: Duration for which offline access is allowed.
              properties:
                value:
                  type: integer
                  description: Value for the offline verification duration.
                  example: 30
                unit:
                  type: string
                  enum:
                    - 'hours'
                    - 'days'
                    - 'attempts'
                  description: Unit for the offline verification duration.
                  example: 'hours'
            bypass_mfa_connection_error:
              type: boolean
              description: Indicates if MFA can be bypassed in case of connection errors.
              example: true

    secondaryFactor:
      type: object
      description: Configuration for secondary factors required for the action.
      properties:
        no_of_required_factors:
          type: integer
          description: Minimum number of secondary factors required for the action.
          example: 1
        factor_configs:
          type: array
          description: List of factor configurations for secondary authentication.
          items:
            $ref: '#/components/schemas/mfaFactorConfigs'
    mfaFactorConfigs:
      type: object
      description: Configuration for multi-factor authentication factors.
      properties:
        authn_factor_config_id:
          type: integer
          description: Unique identifier for the authentication factor configuration.
          example: 200000012544
        verification_order:
          type: integer
          description: Order of verification for the authentication factor.
          example: 1

    groups:
      type: array
      items:
        $ref: '#/components/schemas/groupResource'
      example:
        - id: '2000000092616'
          name: 'Admins'
          type: 'static'
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
        - id: '2000000092617'
          name: 'Users'
          type: 'dynamic'
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
    groupResource:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the group.
          example: '2000000092616'
        name:
          type: string
          description: Name of the group.
          example: 'Admins'
        type:
          type: string
          description: Type of the group.
          enum:
            - static
            - dynamic
          example: static
        primary_source:
          $ref: '#/components/schemas/primarySource'
    devices:
      type: array
      items:
        $ref: '#/components/schemas/deviceResource'
      example:
        - id: '2000000092642'
          name: 'Device 01'
          join_type: 'Id360 Joined'
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
          agent_status: 'Active'
        - id: '2000000092643'
          name: 'Device 02'
          join_type: 'Entra Joined'
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
          agent_status: 'Inactive'
    deviceResource:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the device.
          example: '2000000092642'
        name:
          type: string
          description: Name of the device.
          example: 'Device 01'
        join_type:
          type: string
          description: Type of device join.
          enum:
            - Id360 Joined
            - Entra Joined
          example: Id360 Joined
        primary_source:
          $ref: '#/components/schemas/primarySource'
    primarySource:
      type: object
      description: Primary source of the resource.
      properties:
        id:
          type: string
          description: Unique identifier of the primary source.
          example: '2000000002642'
        name:
          type: string
          description: Name of the primary source.
          example: 'admp.com'
        application_service:
          type: object
          description: Service to which the primary source belongs.
          properties:
            id:
              type: string
              description: Unique identifier of the service.
              example: '2000000002642'
            display_name:
              type: string
              description: Display name of the service.
              example: 'Universal Directory'
            name:
              type: string
              description: Name of the service.
              example: 'ZOHO_DIRECTORY'
            logo:
              type: string
              description: URL of the service logo.
              example: 'https://example.com/logo.png'

    meta:
      type: object
      properties:
        start_index:
          type: integer
          description: The starting index of the records in the response.
          example: 1
        limit:
          type: integer
          description: The maximum number of records returned in the response.
          example: 100
        total_no_of_objects:
          type: integer
          description: The total number of records available for the request.
          example: 1

    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:
        authorizationCode:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          tokenUrl: 'https://accounts.zoho.com/oauth/v2/token'
          scopes:
            id360.conditional_access_policy.read: 'Read access for management actions'
            id360.conditional_access_policy.write: 'Write access for management actions'
            id360.conditional_access_policy.create: 'Create access for management actions'
            id360.conditional_access_policy.delete: 'Delete access for management actions'
            id360.conditional_access_policy.update: 'Update access for management actions'
            id360.conditional_access_policy.all: 'All access for management actions'