# Kiteworks API — devices Operations

**9 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/devices.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/devices.json)

> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.

---

## GET /rest/devices

**Summary:** 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:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `installTagId` | query | no | Unique identifier of install tag for this Device |
| `installTagId:contains` | query | no | Unique identifier of install tag for this Device. Search for results that contain the specified characters in this parameter. |
| `userId` | query | no | Unique identifier of user for this Device |
| `userId:in` | query | no | Unique identifier of user for this Device. Search for results that match any of the specified values for this parameter. |
| `clientId` | query | no | Unique identifier of client for this Device |
| `clientId:contains` | query | no | Unique identifier of client for this Device. Search for results that contain the specified characters in this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of device records. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Device list):**

```json
{
  "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
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/devices" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/devices"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
```

---

## POST /rest/devices

**Summary:** 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:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `clientId` | string | no | Unique identifier of client for this Device |
| `userId` | string | no | Unique identifier of user for this Device |
| `installTagId` | string | no | Unique identifier of the install tag for this device. Usually the serial number of the device |
| `installName` | string | no | Install Tag name for this Device. e.g. Someone's IPhone |
| `mobileKeyStore` | string | no | Key to encrypt files on this device |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the newly registered device record. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 409 | Conflict  <i>Possible error codes: </i>ERR_ENTITY_EXISTS |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Device registered):**

```json
{
  "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 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**409 (ERR_ENTITY_EXISTS):**

```json
{
  "errors": {
    "code": "ERR_ENTITY_EXISTS",
    "message": "Entity exists"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

```json
{
  "errors": {
    "code": "ERR_INPUT_REQUIRED",
    "message": "Field is required"
  }
}
```

**Code Samples:**

**cURL:**

```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:**

```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())
```

---

## PATCH /rest/devices/me/actions/wipe

**Summary:** Report wipe completed

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

| Code | Description |
|------|-------------|
| 200 | Wipe completion acknowledged. Returns no content. |
| 490 | Request blocked by WAF |

**Code Samples:**

**cURL:**

```shell
curl -X PATCH \
  "https://{instance}.kiteworks.com/rest/devices/me/actions/wipe" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```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())
```

---

## GET /rest/devices/{id}

**Summary:** Get a device

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

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the device. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the device record. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Device):**

```json
{
  "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
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/devices/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```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())
```

---

## PUT /rest/devices/{id}

**Summary:** Update a device

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

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the device. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `mobileKeyStore` | string | no | Key to encrypt files on this device |
| `registrationToken` | string | no | Set the token for messaging registration |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the updated device record. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Device updated):**

```json
{
  "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 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

```json
{
  "errors": {
    "code": "ERR_INPUT_REQUIRED",
    "message": "Field is required"
  }
}
```

**Code Samples:**

**cURL:**

```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:**

```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())
```

---

## DELETE /rest/devices/{id}

**Summary:** Delete a device

Deletes the specified device.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the device. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The device was successfully deleted. Returns no content. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_USER",
    "message": "Insufficient access permissions"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/devices/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```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())
```

---

## GET /rest/devices/{install_tag_id}/wipe

**Summary:** 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:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `install_tag_id` | path | yes | The unique install tag identifier for the device, usually the device serial number. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns an object containing the wipe status flag for the device. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Wipe status):**

```json
{
  "status": 0
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/devices/:install_tag_id/wipe" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```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())
```

---

## GET /rest/users/{id}/devices

**Summary:** List devices for a user

Returns a list of devices registered to the specified user.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user whose devices to be retrieved |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a paginated list of device records for the specified user. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (User device list):**

```json
{
  "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
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/:id/devices" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```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())
```

---

## DELETE /rest/devices/me/actions/logout

**Summary:** 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.
**Responses:**

| Code | Description |
|------|-------------|
| 200 | The user has been successfully logged out. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 490 | Request blocked by WAF |

**Response Examples:**

**401 (ERR_AUTH_INVALID_CSRF):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_INVALID_CSRF",
      "message": "Invalid CSRF Authentication"
    }
  ]
}
```

**401 (ERR_AUTH_UNAUTHORIZED):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_UNAUTHORIZED",
      "message": "Unauthorized"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/devices/me/actions/logout" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```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())
```

---