{
"openapi": "3.0.2",
"info": {
"version": "28",
"title": "Kiteworks API — devices Operations"
},
"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"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/devices\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/devices\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"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
Possible error codes: 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
Possible error codes: 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
Possible error codes: 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"
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X POST \\\n \"https://{instance}.kiteworks.com/rest/devices\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"clientId\": \"string\",\n \"userId\": \"string\",\n \"installTagId\": \"string\",\n \"installName\": \"string\",\n \"mobileKeyStore\": \"string\",\n \"addLinks\": true\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/devices\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"clientId\": \"string\",\n \"userId\": \"string\",\n \"installTagId\": \"string\",\n \"installName\": \"string\",\n \"mobileKeyStore\": \"string\",\n \"addLinks\": true\n}\nresponse = requests.post(url, headers=headers, json=payload)\nprint(response.json())"
}
]
}
},
"/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,
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PATCH \\\n \"https://{instance}.kiteworks.com/rest/devices/me/actions/wipe\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/devices/me/actions/wipe\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.patch(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/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"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/devices/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the device.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/devices/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
},
"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
Possible error codes: 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
Possible error codes: 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"
}
}
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PUT \\\n \"https://{instance}.kiteworks.com/rest/devices/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"mobileKeyStore\": \"string\",\n \"registrationToken\": \"string\",\n \"addLinks\": true\n }'"
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the device.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/devices/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"Content-Type\": \"application/json\",\n}\npayload = {\n \"mobileKeyStore\": \"string\",\n \"registrationToken\": \"string\",\n \"addLinks\": true\n}\nresponse = requests.put(url, headers=headers, json=payload)\nprint(response.json())"
}
]
},
"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
Possible error codes: 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"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/devices/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the device.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/devices/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/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"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/devices/:install_tag_id/wipe\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\ninstall_tag_id = \"VALUE\" # The unique install tag identifier for the device, usually the device serial number.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/devices/{install_tag_id}/wipe\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/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"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/users/:id/devices\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # ID of the user whose devices to be retrieved\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/users/{id}/devices\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/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
Possible error codes: 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"
}
},
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/devices/me/actions/logout\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/devices/me/actions/logout\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
}
},
"components": {
"schemas": {
"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"
}
}
}
},
"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."
}
}
},
"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.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."
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
}
}
}
}