openapi: 3.0.0
info:
  title: Account Linking
  description: This API allows you to manage the settings for linking local accounts on devices with Identity360 accounts.
  version: 1.0.0
servers:
  - url: 'https://id360.manageengine.com/api/v1'
    description: 'API Endpoint'
tags:
  - name: device-account-linking
    description: Device Account Linking Endpoints
paths:
  /device-account-linking:
    get:
      tags:
        - device-account-linking
      summary: 'Get Device Account Linking Settings'
      description: 'The Get Device Account Linking Settings API can be used to get the settings for linking local accounts on devices with Identity360 accounts.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceAccountLinkingSettings'
        '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.device.READ
            - id360.device.ALL
    patch:
      tags:
        - device-account-linking
      summary: 'Update Device Account Linking Settings'
      description: 'The Update Device Account Linking Settings API can be used to update the settings for linking local accounts on devices with Identity360 accounts.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceAccountLinkingSettings'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceAccountLinkingSettings'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mandatoryFieldNotFound'
        '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.device.WRITE
            - id360.device.ALL

  /device-account-linking/sync-now:
    post:
      tags:
        - device-account-linking
      summary: 'Sync Device Account Linking'
      description: 'The Sync Device Account Linking API can be used to apply the current account linking settings to all unlinked local accounts on devices.'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/acceptJobResponse'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mandatoryFieldNotFound'
        '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.device.WRITE
            - id360.device.ALL

  /device-account-linking/history:
    get:
      tags:
        - device-account-linking
      summary: 'Get Device Account Linking History'
      description: 'The Get Device Account Linking History API can be used to get the history of account linking operations performed on devices.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/sort'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/deviceAccountLinkingHistories'
                  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.device.READ
            - id360.device.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'
    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'
    from:
      in: query
      name: from
      schema:
        type: integer
        default: 1
      description: >
        Start index for pagination.
      required: false
      example: 1
    id:
      in: path
      name: id
      schema:
        type: string
        example: '2000000000001'
      description: 'The ID of the device to be fetched or deleted'
      required: true
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/deviceAccountLinkingSettings'

    deviceAccountLinkingSettings:
      type: object
      properties:
        is_enabled:
          type: boolean
          example: false
          description: 'Indicates if account linking is enabled'
        attribute_type:
          type: string
          example: 'attribute'
          enum:
            - attribute
            - naming_format
          description: 'Type of attribute used for account linking'
        attribute_value:
          type: string
          example: 'localAccountName'
          description: 'Value of the attribute used for account linking'
        link_restricted_local_accounts:
          type: array
          items:
            type: string
          example:
            - sysadmin
            - administrator
            - recovery
          description: 'List of restricted local accounts that cannot be linked'
        ondemand_provisioning_settings:
          type: object
          properties:
            is_enabled:
              type: boolean
              example: false
              description: 'Indicates if on-demand provisioning is enabled'
            default_permission_level:
              type: string
              example: 'standard'
              enum:
                - standard
                - admin
              description: 'Default permission level for on-demand provisioning'

    deviceAccountLinkingHistories:
      type: array
      items:
        $ref: '#/components/schemas/deviceAccountLinkingHistory'
      example:
        - id: '2000000000001'
          device_name: 'Walter-qa-1'
          link_action: 'Link'
          local_account:
            id: '2000000000001'
            user_name: 'John'
          idp_account:
            user_id: '2000000000002'
            user_name: 'johndoe@company.com'
          action_time: '2021-06-25T06:38:00Z'
          linking_attribute: 'Custom Naming Format1'
          status: 'success'
        - id: '2000000000002'
          device_name: 'Walter-qa-1'
          link_action: 'Unlink'
          local_account:
            id: '2000000000003'
            name: 'Jane'
          idp_account:
            user_id: '2000000000004'
            user_name: 'janesmith@company.com'
          action_time: '2021-06-25T06:38:00Z'
          linking_attribute: 'Custom Naming Format2'
          status: 'failed'
          status_message: 'Local account does not exist in target device'

    deviceAccountLinkingHistory:
      type: object
      properties:
        id:
          type: string
          example: '2000000000001'
          description: 'Unique identifier for the account linking operation'
        device_name:
          type: string
          example: 'Walter-qa-1'
          description: 'Name of the device where the account linking operation was performed'
        link_action:
          type: string
          example: 'Unlink'
          enum:
            - Link
            - Unlink
          description: 'Action performed during the account linking operation'
        local_account:
          type: object
          description: 'Local account details'
          properties:
            id:
              type: string
              example: '2000000000001'
              description: 'Unique identifier for the local account'
            name:
              type: string
              example: 'John'
              description: 'Name of the local account'
        idp_account:
          type: object
          description: 'Identity360 account details linked to the local account'
          properties:
            user_id:
              type: string
              example: '2000000000002'
              description: 'Unique identifier for the Identity360 user account'
            user_name:
              type: string
              example: 'johndoe@company.com'
              description: 'Identity360 account linked to the local account'
        action_time:
          type: string
          format: date-time
          example: '2021-06-25T06:38:00Z'
          description: 'Time when the account linking operation was performed'
        linking_attribute:
          type: string
          example: 'Custom Naming Format1'
          description: 'Attribute used for linking the accounts'
        status:
          type: string
          example: 'failed'
          enum:
            - success
            - failed
          description: 'Status of the account linking operation'
        status_message:
          type: string
          example: 'Local account does not exist in target device'
          description: 'Message providing additional information about the status of the operation'

    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
    acceptJobResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the job.
          example: '2000000293042'
          readOnly: true
        status:
          type: string
          description: Status of the job.
          enum:
            - 'QUEUED'
            - 'RUNNING'
            - 'WARNING'
            - 'COMPLETED'
            - 'ERROR'
          example: RUNNING
          readOnly: true
        message:
          type: string
          description: Message providing additional information about the accept response.
          example: Process is initiated, check jobs for current status.
          readOnly: true

    mandatoryFieldNotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: 00000107
              description: 'Code representing the error'
            title:
              type: string
              example: 'Invalid Parameter'
              description: 'Title of the error'
            detail:
              type: string
              example: Value for mandatory field 'email' is not provided
              description: 'Detailed message about the error'
    unauthorized:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000101'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Unauthorized'
              description: 'Title of the error'
            detail:
              type: string
              example: 'The OAuth token is invalid.'
              description: 'Detailed message about the error'
    serverError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000000'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Internal Server Error'
              description: 'Title of the error'
            detail:
              type: string
              example: 'An unexpected internal error has occurred on the server. Please try again later.'
              description: 'Detailed message about the error'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      x-authorization-example: 'Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            id360.device.read: 'Read Device from the account'
            id360.device.write: 'Create/Update/Delete Device in the account'
            id360.device.create: 'Create Device in the account'
            id360.device.delete: 'Delete User from the account'
            id360.device.update: 'Update Device in the account'
            id360.device.all: 'Perfrom all actions on Device'
        authorizationCode:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          tokenUrl: 'https://accounts.zoho.com/oauth/v2/token'
          scopes:
            id360.device.read: 'Read Device from the account'
            id360.device.write: 'Create/Update/Delete Device in the account'
            id360.device.create: 'Create Device in the account'
            id360.device.delete: 'Delete User from the account'
            id360.device.update: 'Update Device in the account'
            id360.device.all: 'Perfrom all actions on Device'
        clientCredentials:
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            id360.device.read: 'Read Device from the account'
            id360.device.write: 'Create/Update/Delete Device in the account'
            id360.device.create: 'Create Device in the account'
            id360.device.delete: 'Delete User from the account'
            id360.device.update: 'Update Device in the account'
            id360.device.all: 'Perfrom all actions on Device'
        password:
          tokenUrl: https://accounts.zoho.com/oauth/v2/token
          scopes:
            id360.device.read: 'Read Device from the account'
            id360.device.write: 'Create/Update/Delete Device in the account'
            id360.device.create: 'Create Device in the account'
            id360.device.delete: 'Delete User from the account'
            id360.device.update: 'Update Device in the account'
            id360.device.all: 'Perfrom all actions on Device'