openapi: 3.0.0
info:
  title: Accounts
  description: This API Document describes the APIs for local accounts on devices in Identity360.
  version: 1.0.0
servers:
  - url: 'https://id360.manageengine.com/api/v1'
    description: 'API Endpoint'
tags:
  - name: device-account
    description: Devices Endpoints
paths:
  /devices/{device_id}/accounts:
    get:
      tags:
        - device-account-account
      summary: 'List Device Local Accounts'
      description: 'The List Devices Local Accounts API allows you to fetch the list of local accounts associated with a device.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/limit'
        - $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/deviceLocalAccounts'
                  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

  /devices/{device_id}/accounts/{account_id}/link:
    post:
      tags:
        - device-account-account
      summary: 'Link Device Local Account to IdP'
      description: 'The Link Device Local Account to IdP API allows you to link a local account on a device to an Identity Provider (IdP).'
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/deviceLocalAccount'
      responses:
        '202':
          description: 'Accepted'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/acceptJobResponse'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '403':
          description: 'Access Denied'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accessDenied'
        '404':
          description: 'Device Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.write
            - id360.device.all

  /devices/{device_id}/accounts/{account_id}/cancel-link:
    post:
      tags:
        - device-account
      summary: 'Cancel Link of Device Local Account to IdP'
      description: 'The Cancel Link of Device Local Account to IdP API allows you to cancel the link between a local account on a device and an Identity Provider (IdP).'
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/accountId'
      responses:
        '204':
          description: No Content
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Device Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '422':
          description: 'Account Already Linked'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/accountAlreadyLinked'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.write
            - id360.device.all

  /devices/{device_id}/accounts/{account_id}/unlink:
    post:
      tags:
        - device-account
      summary: 'Unlink Device Local Account from IdP'
      description: 'The Unlink Device Local Account from IdP API allows you to unlink a local account on a device from IdP.'
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unlinkDeviceLocalAccount'
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/acceptJobResponse'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Device Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '422':
          description: 'Mandatory Field Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mandatoryFieldNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.write
            - id360.device.all

  /devices/{device_id}/link-restricted-users:
    get:
      tags:
        - device-account
      summary: 'List Link Restricted Users'
      description: 'The List Link Restricted Users API allows you to fetch the list of users who are restricted from linking to a device.'
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/from'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/linkRestrictedUsers'
                  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
    delete:
      tags:
        - device-account
      summary: 'Unrestrict Link Restricted Users'
      description: 'The Unrestrict Link Restricted Users API allows you to remove the restriction on users who are restricted from linking to a device.'
      parameters:
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/ids'
      responses:
        '204':
          description: No Content
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Device Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deviceNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.device.write
            - id360.device.delete
            - 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
    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'
    deviceId:
      in: path
      name: device_id
      schema:
        type: string
        example: '2000000000001'
      description: 'The ID of the device to be fetched or deleted'
      required: true
    accountId:
      in: path
      name: account_id
      schema:
        type: string
        example: '2000000000101'
      description: 'The ID of the local account to be linked to the IdP.'
      required: true
    ids:
      in: query
      name: ids
      schema:
        type: string
      description: >
        Comma-separated list of resource IDs.
        <br>
        <strong>eg:</strong> 2000000000011,2000000000012
      required: true
      example: '2000000000011,2000000000012'
  schemas:
    gendoc-attributes-schema:
      $ref: '#/components/schemas/deviceLocalAccount'

    deviceLocalAccounts:
      type: array
      description: 'List of device local accounts'
      items:
        $ref: '#/components/schemas/deviceLocalAccount'
      example:
        - id: 2000000000001
          user_name: Johnson
          permission_level: Admin
          last_login: null
          is_idp_linked: false
        - id: 2000000000002
          user_name: Mike
          permission_level: Standard
          last_login: "2023-10-26T03:30:00Z"
          is_idp_linked: true
          idp_account_details:
            user_id: 2000000000011
            user_name: Mike@mydomain.com
            display_name: Mike
            link_type: Manual
            link_status: linked
            linked_at: "2023-10-26T03:30:00Z"
        - id: 2000000000003
          user_name: Dani
          permission_level: Admin
          last_login: null
          is_idp_linked: false
        - id: 2000000000004
          user_name: Rose
          permission_level: Standard
          last_login: "2023-10-26T03:30:00Z"
          is_idp_linked: true
          idp_account_details:
            user_id: 2000000000012
            user_name: Capt@mydomain.com
            display_name: Capt
            link_type: Automatic
            link_status: linked
            linked_at: "2023-10-26T03:30:00Z"

    deviceLocalAccount:
      type: object
      description: 'Device Account details'
      properties:
        id:
          type: integer
          description: Unique identifier for the device local account.
          example: 2000000000001
          readOnly: true
        user_name:
          type: string
          description: Local account name associated with the device.
          example: 'john.doe'
          readOnly: true
        permission_level:
          type: string
          description: Permission level of the device account.
          example: 'Standard'
          enum:
            - 'Standard'
            - 'Administrator'
        last_login:
          type: string
          format: date-time
          description: Last login time of the device account.
          example: "2023-10-01T12:00:00Z"
          readOnly: true
        is_idp_linked:
          type: boolean
          description: Indicates if the device account is linked to an Identity Provider (IdP).
          example: true
          readOnly: true
        idp_user_id:
          type: string
          description: Unique identifier for the user in the IdP.
          example: '2000000000011'
          writeOnly: true
        idp_user_details:
          type: object
          description: Details of the linked IdP account.
          readOnly: true
          properties:
            user_id:
              type: integer
              description: Unique identifier for the user in the IdP.
              example: 2000000000011
            user_name:
              type: string
              description: Username of the IdP account.
              example: "johndoe@mydomain.com"
            display_name:
              type: string
              description: Display name of the IdP account.
              example: "John Doe"
            link_type:
              type: string
              description: Type of link between the device account and IdP.
              example: "Manual"
            link_status:
              type: string
              description: Status of the link between the device account and IdP.
              example: "pending_link"
            linked_at:
              type: string
              format: date-time
              description: Timestamp when the device account was linked to the IdP.
              example: "2023-10-01T12:00:00Z"

    unlinkDeviceLocalAccount:
      type: object
      description: 'Unlink Device Local Account from IdP'
      properties:
        type:
          type: string
          description: Type of unlink operation to be performed.
          example: 'unlink_and_change_password'
          enum:
            - 'unlink_and_change_password'
            - 'unlink_and_suspend'
          writeOnly: true
        new_password:
          type: string
          description: New password to be set for the device local account. Only required if type is 'unlink_and_change_password'.
          example: 'S3cure@123'
          writeOnly: true
        restrict_relink_for_idp_account:
          type: boolean
          description: Restrict re-linking of the IdP account to the device local account after unlinking.
          example: false
          writeOnly: true

    linkRestrictedUsers:
      type: array
      description: 'List of users restricted from linking to the device'
      items:
        $ref: '#/components/schemas/linkRestrictedUser'
      example:
        - id: "2000000000011"
          display_name: "AlexHales"
          user_name: "alexhales@company.com"
          unlinked_time: "2024-07-15T14:20:00Z"
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
        - id: "2000000000012"
          display_name: "JohnDoe"
          user_name: "johndoe@company.com"
          unlinked_time: "2024-07-16T09:30:00Z"
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
        - id: "2000000000013"
          display_name: "JaneSmith"
          user_name: "janesmith@company.com"
          unlinked_time: "2024-07-17T15:45:00Z"
          primary_source:
            id: '2000000072637'
            name: 'Berge-Corp'
            application_service:
              id: '2000000018007'
              display_name: 'Universal Directory'
              name: 'ZOHO_DIRECTORY'
              logo: 'universal-directory'
    linkRestrictedUser:
      type: object
      description: 'User restricted from linking to the device'
      properties:
        id:
          type: string
          description: Unique identifier for the user.
          example: '2000000000011'
        display_name:
          type: string
          description: Display name of the user.
          example: 'AlexHales'
        user_name:
          type: string
          description: Username of the user.
          example: 'alexhales@company.com'
        unlinked_time:
          type: string
          format: date-time
          description: Timestamp when the user was unlinked from the device.
          example: '2024-07-15T14:20:00Z'
        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
    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
    accessDenied:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '********'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Access Denied'
              description: 'Title of the error'
            detail:
              type: string
              example: 'You do not have permission to do this operation.'
              description: 'Detailed message about the error'
    deviceNotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '********'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Device Not Found'
              description: 'Title of the error'
            detail:
              type: string
              example: 'No device found with ID 2000000000001.'
              description: 'Detailed message about the error'
    accountAlreadyLinked:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '********'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Account is linked'
              description: 'Title of the error'
            detail:
              type: string
              example: 'The account is already linked and cannot be canceled. Please use the unlink action instead.'
              description: 'Detailed message about the error'
    mandatoryFieldNotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '********'
              description: 'Code representing the error'
            title:
              type: string
              example: 'Missing required field'
              description: 'Title of the error'
            detail:
              type: string
              example: The parameter new_password is required
              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'