openapi: 3.0.2
info:
  version: '28'
  title: Kiteworks API Documentation activities devices API
tags:
- name: devices
paths:
  /rest/devices:
    get:
      tags:
      - devices
      summary: List devices
      description: Returns a list of devices per user that have authenticated on this server. Each record includes the device name (e.g. iPad, iPhone), install tag ID, client ID, and remote wipe flag.
      responses:
        '200':
          description: Returns a paginated list of device records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                Device list:
                  summary: Two registered devices for a user
                  value:
                    data:
                    - id: 101
                      client_id: mobile_app_ios
                      user_id: 5
                      install_tag_id: ABC123DEF456
                      install_name: Work iPhone
                      wipe_flag: 0
                      mobile_key_store: null
                    - id: 102
                      client_id: mobile_app_ios
                      user_id: 5
                      install_tag_id: DEF456GHI789
                      install_name: Work iPad
                      wipe_flag: 0
                      mobile_key_store: null
                    total: 2
                    page: 1
                    pageSize: 20
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: installTagId
        description: Unique identifier of install tag for this Device
        schema:
          type: string
      - in: query
        name: installTagId:contains
        description: Unique identifier of install tag for this Device. Search for results that contain the specified characters in this parameter.
        schema:
          type: string
      - in: query
        name: userId
        description: Unique identifier of user for this Device
        schema:
          type: string
      - in: query
        name: userId:in
        description: Unique identifier of user for this Device. Search for results that match any of the specified values for this parameter.
        schema:
          type: string
      - in: query
        name: clientId
        description: Unique identifier of client for this Device
        schema:
          type: string
      - in: query
        name: clientId:contains
        description: Unique identifier of client for this Device. Search for results that contain the specified characters in this parameter.
        schema:
          type: string
      - in: query
        name: orderBy
        description: Sorting options
        schema:
          type: array
          items:
            type: string
          enum:
          - id:asc
          - id:desc
          - installTagId:asc
          - installTagId:desc
          - userId:asc
          - userId:desc
          - clientId:asc
          - clientId:desc
      - in: query
        name: offset
        description: Offset
        schema:
          type: integer
      - in: query
        name: limit
        description: Limit
        schema:
          type: integer
      - in: query
        name: with
        description: With parameters
        schema:
          type: string
      - in: query
        name: mode
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - full_with_links
          - full
          - compact
    post:
      tags:
      - devices
      summary: Register a device
      description: Registers a new device for a user. Called when a user logs in to Kiteworks to track the device they are using.
      responses:
        '200':
          description: Returns the newly registered device record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
              examples:
                Device registered:
                  summary: A newly registered device
                  value:
                    id: 103
                    client_id: mobile_app_ios
                    user_id: 5
                    install_tag_id: GHI789JKL012
                    install_name: Work MacBook
                    wipe_flag: 0
                    mobile_key_store: null
        '403':
          description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ACCESS_USER:
                  summary: Insufficient access permissions
                  description: Insufficient access permissions
                  value:
                    errors:
                      code: ERR_ACCESS_USER
                      message: Insufficient access permissions
        '409':
          description: 'Conflict<br /><br /><i>Possible error codes: </i>ERR_ENTITY_EXISTS'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ENTITY_EXISTS:
                  summary: Entity exists
                  description: Entity exists
                  value:
                    errors:
                      code: ERR_ENTITY_EXISTS
                      message: Entity exists
        '422':
          description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_INPUT_REQUIRED:
                  summary: Field is required
                  description: Field is required
                  value:
                    errors:
                      code: ERR_INPUT_REQUIRED
                      message: Field is required
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: query
        name: returnEntity
        description: If set to `true`, returns information about the newly created entity.
        schema:
          type: boolean
      - in: query
        name: mode
        description: Determines the detail level of the response body.
        schema:
          type: string
          enum:
          - full_with_links
          - full
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Device.Post'
  /rest/devices/me/actions/wipe:
    patch:
      tags:
      - devices
      summary: Report wipe completed
      description: Notifies the server that the current device has completed a requested remote wipe. Updates the wipe flag to completed.
      responses:
        '200':
          description: Wipe completion acknowledged. Returns no content.
        '490':
          description: Request blocked by WAF
      deprecated: false
  /rest/devices/{id}:
    get:
      tags:
      - devices
      summary: Get a device
      description: Returns the details of the specified device, including device name, install tag ID, client ID, and remote wipe flag.
      responses:
        '200':
          description: Returns the device record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
              examples:
                Device:
                  summary: A single device record
                  value:
                    id: 101
                    client_id: mobile_app_ios
                    user_id: 5
                    install_tag_id: ABC123DEF456
                    install_name: Work iPhone
                    wipe_flag: 0
                    mobile_key_store: null
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: The unique identifier of the device.
        required: true
        schema:
          type: integer
    put:
      tags:
      - devices
      summary: Update a device
      description: Updates the details of the specified device. Supports updating the mobile key store and messaging registration token.
      responses:
        '200':
          description: Returns the updated device record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
              examples:
                Device updated:
                  summary: Device with updated mobile key store
                  value:
                    id: 101
                    client_id: mobile_app_ios
                    user_id: 5
                    install_tag_id: ABC123DEF456
                    install_name: Work iPhone
                    wipe_flag: 0
                    mobile_key_store: base64encodedkey==
        '403':
          description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ACCESS_USER:
                  summary: Insufficient access permissions
                  description: Insufficient access permissions
                  value:
                    errors:
                      code: ERR_ACCESS_USER
                      message: Insufficient access permissions
        '422':
          description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_INPUT_REQUIRED:
                  summary: Field is required
                  description: Field is required
                  value:
                    errors:
                      code: ERR_INPUT_REQUIRED
                      message: Field is required
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: The unique identifier of the device.
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Device.Put'
    delete:
      tags:
      - devices
      summary: Delete a device
      description: Deletes the specified device.
      responses:
        '204':
          description: The device was successfully deleted. Returns no content.
        '403':
          description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_ACCESS_USER:
                  summary: Insufficient access permissions
                  description: Insufficient access permissions
                  value:
                    errors:
                      code: ERR_ACCESS_USER
                      message: Insufficient access permissions
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: The unique identifier of the device.
        required: true
        schema:
          type: string
  /rest/devices/{install_tag_id}/wipe:
    get:
      tags:
      - devices
      summary: Get the wipe status
      description: Returns the remote wipe status of the specified device, identified by its install tag ID (usually the device serial number).
      responses:
        '200':
          description: Returns an object containing the wipe status flag for the device.
          content:
            application/json:
              schema:
                type: integer
              examples:
                Wipe status:
                  summary: Wipe status for a device
                  value:
                    status: 0
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: install_tag_id
        description: The unique install tag identifier for the device, usually the device serial number.
        required: true
        schema:
          type: string
  /rest/users/{id}/devices:
    get:
      tags:
      - devices
      summary: List devices for a user
      description: Returns a list of devices registered to the specified user.
      responses:
        '200':
          description: Returns a paginated list of device records for the specified user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
                  metadata:
                    $ref: '#/components/schemas/MetaData'
              examples:
                User device list:
                  summary: Devices registered to a user
                  value:
                    data:
                    - id: 101
                      client_id: mobile_app_ios
                      user_id: 5
                      install_tag_id: ABC123DEF456
                      install_name: Work iPhone
                      wipe_flag: 0
                      mobile_key_store: null
                    total: 1
                    page: 1
                    pageSize: 20
        '490':
          description: Request blocked by WAF
      deprecated: false
      parameters:
      - in: path
        name: id
        description: ID of the user whose devices to be retrieved
        required: true
        schema:
          type: string
  /rest/devices/me/actions/logout:
    delete:
      summary: Log out the current user
      description: "### Description:\n  Logs out the current user and invalidates the active session.\n### Precondition:\n  User must have an active session.\n### Response:\n  Returns logout confirmation details.\n"
      tags:
      - devices
      responses:
        '200':
          description: The user has been successfully logged out.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Logout'
        '401':
          description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              examples:
                ERR_AUTH_INVALID_CSRF:
                  summary: Invalid CSRF Authentication
                  description: Invalid CSRF Authentication
                  value:
                    errors:
                    - code: ERR_AUTH_INVALID_CSRF
                      message: Invalid CSRF Authentication
                ERR_AUTH_UNAUTHORIZED:
                  summary: Unauthorized
                  description: Unauthorized
                  value:
                    errors:
                    - code: ERR_AUTH_UNAUTHORIZED
                      message: Unauthorized
        '490':
          description: Request blocked by WAF
components:
  schemas:
    Errors:
      type: object
      properties:
        error:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    Device.Post:
      description: Class Device
      properties:
        clientId:
          description: Unique identifier of client for this Device
          type: string
        userId:
          description: Unique identifier of user for this Device
          type: string
        installTagId:
          description: Unique identifier of the install tag for this device. Usually the serial number of the device
          type: string
        installName:
          description: Install Tag name for this Device. e.g. Someone's IPhone
          type: string
        mobileKeyStore:
          description: Key to encrypt files on this device
          type: string
        addLinks:
          description: Indicates whether HATEOAS links should be included in the response
          type: boolean
    Device:
      description: Class Device
      required:
      - clientId
      - id
      - installName
      - userId
      properties:
        id:
          description: Unique identifier of Device
          type: integer
        clientId:
          description: Unique identifier of client for this Device
          type: string
        userId:
          description: Unique identifier of user for this Device
          type: string
        installTagId:
          description: Unique identifier of the install tag for this device. Usually the serial number of the device
          type: string
        installName:
          description: Install Tag name for this Device. e.g. Someone's IPhone
          type: string
        wipeFlag:
          description: "Flag that tells the device to remote wipe itself.\n     *                   0 = not set, 1 = set, 2 = device has been notified, 3 = wipe is completed"
          type: string
        mobileKeyStore:
          description: Key to encrypt files on this device
          type: string
        links:
          description: HATEOAS links associated with the entity
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Error message
    Device.Put:
      description: Class Device
      properties:
        mobileKeyStore:
          description: Key to encrypt files on this device
          type: string
        registrationToken:
          description: Set the token for messaging registration
          type: string
        addLinks:
          description: Indicates whether HATEOAS links should be included in the response
          type: boolean
    Logout:
      type: object
      properties:
        redirectUri:
          type: string
          description: URL to redirect to after logout.
    MetaData:
      type: object
      properties:
        total:
          type: integer
          description: Total number of items available.
        limit:
          type: integer
          description: Maximum number of items returned per page.
        offset:
          type: integer
          description: Number of items skipped before the current page.