devices

9 endpoints
GET/rest/devices

List devices

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.

Parameters
Query Parameters
installTagId
Optional
string

Unique identifier of install tag for this Device

installTagId:contains
Optional
string

Unique identifier of install tag for this Device. Search for results that contain the specified characters in this parameter.

userId
Optional
string

Unique identifier of user for this Device

userId:in
Optional
string

Unique identifier of user for this Device. Search for results that match any of the specified values for this parameter.

clientId
Optional
string

Unique identifier of client for this Device

clientId:contains
Optional
string

Unique identifier of client for this Device. Search for results that contain the specified characters in this parameter.

orderBy
Optional
string[]

Sorting options

offset
Optional
integer

Offset

limit
Optional
integer

Limit

with
Optional
string

With parameters

mode
Optional
string

Determines the detail level of the response body.

Responses

Returns a paginated list of device records.

id
Required
integer

Unique identifier of Device

clientId
Required
string

Unique identifier of client for this Device

userId
Required
string

Unique identifier of user for this Device

installTagId
string

Unique identifier of the install tag for this device. Usually the serial number of the device

installName
Required
string

Install Tag name for this Device. e.g. Someone's IPhone

wipeFlag
string

Flag that tells the device to remote wipe itself.

  • 0 = not set, 1 = set, 2 = device has been notified, 3 = wipe is completed

mobileKeyStore
string

Key to encrypt files on this device

links
string[]

HATEOAS links associated with the entity

total
integer

Total number of items available.

limit
integer

Maximum number of items returned per page.

offset
integer

Number of items skipped before the current page.

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/devices" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/devices"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "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 }
// Error - No Body
POST/rest/devices

Register a device

Registers a new device for a user. Called when a user logs in to Kiteworks to track the device they are using.

Parameters
Query Parameters
returnEntity
Optional
boolean

If set to true, returns information about the newly created entity.

mode
Optional
string

Determines the detail level of the response body.

Request Body
clientId
string

Unique identifier of client for this Device

userId
string

Unique identifier of user for this Device

installTagId
string

Unique identifier of the install tag for this device. Usually the serial number of the device

installName
string

Install Tag name for this Device. e.g. Someone's IPhone

mobileKeyStore
string

Key to encrypt files on this device

addLinks
boolean

Indicates whether HATEOAS links should be included in the response

Responses

Returns the newly registered device record.

id
Required
integer

Unique identifier of Device

clientId
Required
string

Unique identifier of client for this Device

userId
Required
string

Unique identifier of user for this Device

installTagId
string

Unique identifier of the install tag for this device. Usually the serial number of the device

installName
Required
string

Install Tag name for this Device. e.g. Someone's IPhone

wipeFlag
string

Flag that tells the device to remote wipe itself.

  • 0 = not set, 1 = set, 2 = device has been notified, 3 = wipe is completed

mobileKeyStore
string

Key to encrypt files on this device

links
string[]

HATEOAS links associated with the entity

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Conflict

Possible error codes: ERR_ENTITY_EXISTS

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/devices" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "clientId": "string",
         "userId": "string",
         "installTagId": "string",
         "installName": "string",
         "mobileKeyStore": "string",
         "addLinks": true
       }'
Python
import requests

url = "https://{instance}.kiteworks.com/rest/devices"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "clientId": "string",
  "userId": "string",
  "installTagId": "string",
  "installName": "string",
  "mobileKeyStore": "string",
  "addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
Responses
{ "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 }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
{ "errors": { "code": "ERR_ENTITY_EXISTS", "message": "Entity exists" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
PATCH/rest/devices/me/actions/wipe

Report wipe completed

Notifies the server that the current device has completed a requested remote wipe. Updates the wipe flag to completed.

This endpoint requires no parameters.
Responses

Wipe completion acknowledged. Returns no content.

Empty response body.

Request blocked by WAF

Empty response body.
Shell
curl -X PATCH \
  "https://{instance}.kiteworks.com/rest/devices/me/actions/wipe" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/devices/me/actions/wipe"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.patch(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
// Error - No Body
GET/rest/devices/{id}

Get a device

Returns the details of the specified device, including device name, install tag ID, client ID, and remote wipe flag.

Parameters
Path Parameters
id
Required
integer

The unique identifier of the device.

Responses

Returns the device record.

id
Required
integer

Unique identifier of Device

clientId
Required
string

Unique identifier of client for this Device

userId
Required
string

Unique identifier of user for this Device

installTagId
string

Unique identifier of the install tag for this device. Usually the serial number of the device

installName
Required
string

Install Tag name for this Device. e.g. Someone's IPhone

wipeFlag
string

Flag that tells the device to remote wipe itself.

  • 0 = not set, 1 = set, 2 = device has been notified, 3 = wipe is completed

mobileKeyStore
string

Key to encrypt files on this device

links
string[]

HATEOAS links associated with the entity

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/devices/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # The unique identifier of the device.

url = f"https://{{instance}}.kiteworks.com/rest/devices/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "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 }
// Error - No Body
PUT/rest/devices/{id}

Update a device

Updates the details of the specified device. Supports updating the mobile key store and messaging registration token.

Parameters
Path Parameters
id
Required
integer

The unique identifier of the device.

Request Body
mobileKeyStore
string

Key to encrypt files on this device

registrationToken
string

Set the token for messaging registration

addLinks
boolean

Indicates whether HATEOAS links should be included in the response

Responses

Returns the updated device record.

id
Required
integer

Unique identifier of Device

clientId
Required
string

Unique identifier of client for this Device

userId
Required
string

Unique identifier of user for this Device

installTagId
string

Unique identifier of the install tag for this device. Usually the serial number of the device

installName
Required
string

Install Tag name for this Device. e.g. Someone's IPhone

wipeFlag
string

Flag that tells the device to remote wipe itself.

  • 0 = not set, 1 = set, 2 = device has been notified, 3 = wipe is completed

mobileKeyStore
string

Key to encrypt files on this device

links
string[]

HATEOAS links associated with the entity

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/devices/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "mobileKeyStore": "string",
         "registrationToken": "string",
         "addLinks": true
       }'
Python
import requests

id = "VALUE"  # The unique identifier of the device.

url = f"https://{{instance}}.kiteworks.com/rest/devices/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "mobileKeyStore": "string",
  "registrationToken": "string",
  "addLinks": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
Responses
{ "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==" }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
DELETE/rest/devices/{id}

Delete a device

Deletes the specified device.

Parameters
Path Parameters
id
Required
string

The unique identifier of the device.

Responses

The device was successfully deleted. Returns no content.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/devices/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # The unique identifier of the device.

url = f"https://{{instance}}.kiteworks.com/rest/devices/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
GET/rest/devices/{install_tag_id}/wipe

Get the wipe status

Returns the remote wipe status of the specified device, identified by its install tag ID (usually the device serial number).

Parameters
Path Parameters
install_tag_id
Required
string

The unique install tag identifier for the device, usually the device serial number.

Responses

Returns an object containing the wipe status flag for the device.

Empty response body.

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/devices/:install_tag_id/wipe" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

install_tag_id = "VALUE"  # The unique install tag identifier for the device, usually the device serial number.

url = f"https://{{instance}}.kiteworks.com/rest/devices/{install_tag_id}/wipe"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "status": 0 }
// Error - No Body
GET/rest/users/{id}/devices

List devices for a user

Returns a list of devices registered to the specified user.

Parameters
Path Parameters
id
Required
string

ID of the user whose devices to be retrieved

Responses

Returns a paginated list of device records for the specified user.

id
Required
integer

Unique identifier of Device

clientId
Required
string

Unique identifier of client for this Device

userId
Required
string

Unique identifier of user for this Device

installTagId
string

Unique identifier of the install tag for this device. Usually the serial number of the device

installName
Required
string

Install Tag name for this Device. e.g. Someone's IPhone

wipeFlag
string

Flag that tells the device to remote wipe itself.

  • 0 = not set, 1 = set, 2 = device has been notified, 3 = wipe is completed

mobileKeyStore
string

Key to encrypt files on this device

links
string[]

HATEOAS links associated with the entity

total
integer

Total number of items available.

limit
integer

Maximum number of items returned per page.

offset
integer

Number of items skipped before the current page.

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/:id/devices" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # ID of the user whose devices to be retrieved

url = f"https://{{instance}}.kiteworks.com/rest/users/{id}/devices"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "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 }
// Error - No Body
DELETE/rest/devices/me/actions/logout

Log out the current user

Description:

Logs out the current user and invalidates the active session.

Precondition:

User must have an active session.

Response:

Returns logout confirmation details.
This endpoint requires no parameters.
Responses

The user has been successfully logged out.

redirectUri
string

URL to redirect to after logout.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/devices/me/actions/logout" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/devices/me/actions/logout"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
Responses
{ "redirectUri": "string" }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
// Error - No Body
Previouscontacts
Nextdli