# Kiteworks API — users Operations

**36 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/users.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/users.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.

---

## DELETE /rest/users

**Summary:** Deletes Users

Mark the specified users as deleted. The size of request User UUID is limited (recommend <= 100)

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id:in` | query | yes | List of user IDs to delete. |
| `retainToUser` | query | no | The ID of the new owner to whom the data will be transferred, applicable when `retainData` and/or `retainPermissionToSharedData` are set to true. |
| `retainToAdvancedFormUser` | query | no | The ID of the user to whom the advanced form data will be transferred, similar to retainToUser but specifically for advanced form components. |
| `remoteWipe` | query | no | Indicates whether to remotely wipe data from both desktop and mobile devices. |
| `deleteUnsharedData` | query | no | Indicates whether data owned by the user should be deleted. This is required and must be set to True if `retainData` is False, and vice versa. |
| `retainData` | query | no | Indicates whether data should be retained and transferred to another user. This is required and must be True if `deleteUnsharedData` is False, and vice versa. |
| `retainPermissionToSharedData` | query | no | Indicates whether permissions to shared folders should be retained. |
| `withdrawFileLinks` | query | no | Indicates whether files sent by deleted or demoted users should be withdrawn. |
| `withdrawRequestFiles` | query | no | Indicates whether request files sent by deleted or demoted users should be withdrawn. |
| `partialSuccess` | query | no | If set to `true`, the operation will continue for the valid items even if some items result in failure. |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Specified users marked as deleted. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN, ERR_INPUT_ATTRIBUTE_FORBIDDEN, ERR_INPUT_REQUIRED, ERR_INPUT_NOT_STRING |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

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

**422 (ERR_INPUT_NOT_BOOLEAN):**

```json
{
  "errors": {
    "code": "ERR_INPUT_NOT_BOOLEAN",
    "message": "Input is not a valid boolean"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

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

**Code Samples:**

**cURL:**

```shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/users?id:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "id:in": "VALUE",
}
response = requests.delete(url, params=params, headers=headers)
print(response.json())
```

---

## POST /rest/users/actions/login

**Summary:** User login

Handles user login by accepting the user credentials (username and password).
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `username` | string | yes | The username of the user attempting to log in. |
| `password` | string | yes | The password of the user. It must be kept confidential and securely stored. |
| `referral` | string | no | The URL that referred the user to this login action. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Login successful. Returns a redirect URL and success status. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (LoginSuccess):**

```json
{
  "success": true,
  "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback"
}
```

**200 (LoginWithTFA):**

```json
{
  "success": false,
  "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/tfa"
}
```

**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/users/actions/login" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "username": "string",
         "password": "string",
         "referral": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/actions/login"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "username": "string",
  "password": "string",
  "referral": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## PUT /rest/users/aliveToken

**Summary:** Updates token state

Updates current session state to be not outdated any more
**Responses:**

| Code | Description |
|------|-------------|
| 200 | Token state updated successfully |
| 490 | Request blocked by WAF |

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## GET /rest/users/ldapSearch

**Summary:** Find users in LDAP by input supplied

Searches the configured LDAP directory for users matching the supplied search criteria.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `value` | query | yes | The user's email or name |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns users found in LDAP matching the supplied search criteria. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (LdapMatches):**

```json
{
  "matches": [
    {
      "email": "jane.doe@example.com",
      "displayName": "Jane Doe"
    },
    {
      "email": "john.smith@example.com",
      "displayName": "John Smith"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/ldapSearch?value=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

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

---

## GET /rest/users/me

**Summary:** Retrieve details of the currently logged-in user

Fetches the details of the currently authenticated user, including their email address and name.
**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the details of the currently authenticated user. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (CurrentUser):**

```json
{
  "id": "abc12345def67890ab",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "active": true,
  "verified": true,
  "suspended": false,
  "deleted": false,
  "deactivated": false,
  "flags": 1,
  "userTypeId": 5,
  "serviceName": "kiteworks",
  "created": "2024-01-15T10:30:00+0000"
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## PUT /rest/users/me

**Summary:** Update the current user's details

Updates the details of the currently authenticated user. For example, change their name or password.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `password` | string | no | The user's password |
| `previousPassword` | string | no | The user's previous password |
| `name` | string | no | The user's name |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Currently authenticated user details updated successfully. Returns the updated user object. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_PASSWORD_COMPLEXITY_ERROR |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (UpdatedMe):**

```json
{
  "id": "abc12345def67890ab",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "active": true,
  "verified": true,
  "suspended": false,
  "deleted": false,
  "deactivated": false,
  "flags": 1,
  "userTypeId": 5,
  "serviceName": "kiteworks",
  "created": "2024-01-15T10:30:00+0000"
}
```

**422 (ERR_INPUT_PASSWORD_COMPLEXITY_ERROR):**

```json
{
  "errors": {
    "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR",
    "message": "Password does not meet complexity requirements"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "password": "string",
         "previousPassword": "string",
         "name": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "password": "string",
  "previousPassword": "string",
  "name": "string"
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/users/me/forcedPasswordChange

**Summary:** Change the password for current user after expired

Change the password for current user after password expired
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `password` | string | no | The user's password |
| `previousPassword` | string | no | The user's previous password |
| `referral` | string | no | referral |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Password changed successfully. Returns a redirect URL for the next step in the authentication flow. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_PASSWORD_COMPLEXITY_ERROR, ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (PasswordChanged):**

```json
{
  "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback"
}
```

**422 (ERR_INPUT_PASSWORD_COMPLEXITY_ERROR):**

```json
{
  "errors": {
    "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR",
    "message": "Password does not meet complexity requirements"
  }
}
```

**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/users/me/forcedPasswordChange" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "password": "string",
         "previousPassword": "string",
         "referral": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/forcedPasswordChange"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "password": "string",
  "previousPassword": "string",
  "referral": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## PUT /rest/users/me/mobileNumber

**Summary:** Update mobile number of the current user

Updates the mobile number used for two-factor authentication for the current user. Requires the user's current password for verification. When the test-only flag is set, sends a test SMS to the provided number without saving it and returns an empty 200 response.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `password` | string | yes | The current password of the user |
| `mobileNumber` | string | yes | The user's new mobile number |
| `testOnly` | boolean | no | If true, a short message will be sent to the number, and the number will not be saved |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Mobile number updated successfully. Returns the updated user settings. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED, ERR_INPUT_INVALID_FORMAT |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (MobileNumberUpdated):**

```json
{
  "languageId": 1,
  "locationId": 2,
  "signature": "",
  "storageUsed": 1048576,
  "storageQuota": 10737418240,
  "mobileNumber": "+14155550199",
  "mobileNumberVerified": false
}
```

**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/users/me/mobileNumber" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "password": "string",
         "mobileNumber": "string",
         "testOnly": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/mobileNumber"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "password": "string",
  "mobileNumber": "string",
  "testOnly": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/users/me/quota

**Summary:** Retrieve user quota

### Description:
  Retrieves the current user's quota details, including send quota and folder storage quota.
### Precondition:
  The user profile must have "Collaboration Allowed" enabled or have mail access.
### Response:
  Returns the user's quota information.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `filter` | query | no | Limit the quota response to a specific quota type. `send` – Returns send quota usage only. `folder` – Returns folder storage quota only. If omitted, both send and folder quota details are returned. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The user quota is successfully retrieved. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 404 | Not Found  <i>Possible error codes: </i>ERR_ENTITY_NOT_FOUND |
| 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"
    }
  ]
}
```

**404 (ERR_ENTITY_NOT_FOUND):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_NOT_FOUND",
      "message": "Entity does not exist"
    }
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/users/me/tfa/auth

**Summary:** Two Factor Authentication

Submits the user's Two-Factor Authentication (TFA) passcode to complete the TFA step of the login flow. Returns a redirect URL on success, or a new challenge message if the TFA module requires an additional round of authentication.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `otp` | string | yes | OTP |
| `referral` | string | no | referral |
| `rememberDevice` | boolean | no | remember device |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Two Factor Authentication completed. Returns either a redirectUrl string on success or a challengeMsg string if an additional challenge is required. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TfaAccepted):**

```json
{
  "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback"
}
```

**200 (TfaRechallenge):**

```json
{
  "challengeMsg": "Incorrect passcode. Please try again."
}
```

**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/users/me/tfa/auth" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "otp": "string",
         "referral": "string",
         "rememberDevice": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/tfa/auth"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "otp": "string",
  "referral": "string",
  "rememberDevice": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/users/me/tfa/challenge

**Summary:** Two Factor Authentication

Initiates a Two-Factor Authentication (TFA) challenge for the current login session. For challenge-response modules, triggers passcode delivery (for example, via SMS or push notification) and returns a challenge message. If the TFA module accepts immediately, returns a redirect URL to advance the login flow.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `referral` | query | no | Referral URL |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Two Factor Authentication challenge initiated successfully. Returns either a challengeMsg string or a redirectUrl string depending on the authentication flow. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (ChallengeInitiated):**

```json
{
  "challengeMsg": "A passcode has been sent to your mobile device."
}
```

**200 (ChallengeAccepted):**

```json
{
  "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback"
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/tfa/challenge" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/tfa/challenge"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.post(url, headers=headers)
print(response.json())
```

---

## GET /rest/users/me/tfa/config

**Summary:** Two Factor Authentication

Returns the Two-Factor Authentication (TFA) configuration for the current login session, including the module name, passcode field labels, and device-remembering settings. For SMSOTP modules, also includes the user's registered mobile number and whether the number can be changed.
**Responses:**

| Code | Description |
|------|-------------|
| 200 | Two Factor Authentication configuration retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TfaConfigSms):**

```json
{
  "module": "SMSOTP",
  "passcodeLabel": "Enter passcode",
  "passcodeDescription": "Enter the code sent to your mobile phone.",
  "rechallengeLabel": "Resend code",
  "challengeShouldSendPassword": false,
  "challengeWaitMessage": "Sending code...",
  "rechallengeMessage": "Resend the passcode",
  "rememberDeviceEnabled": true,
  "passcodeMask": false,
  "mobileNumber": "+1-555****1234",
  "allowNumberChange": true
}
```

**200 (TfaConfigTotp):**

```json
{
  "module": "TOTP",
  "passcodeLabel": "Authenticator code",
  "passcodeDescription": "Enter the 6-digit code from your authenticator app.",
  "rechallengeLabel": "",
  "challengeShouldSendPassword": false,
  "challengeWaitMessage": "",
  "rechallengeMessage": "",
  "rememberDeviceEnabled": true,
  "passcodeMask": false
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/users/me/tfa/resetTotpSecret

**Summary:** Reset secret key for time-based OTP of the current user

Resets the TOTP secret key for the current user. Requires the user's current password. When called without an OTP, generates a new secret and returns setup details including a QR code. When called with an OTP, verifies the new secret and completes the reset.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `password` | string | yes | The user's password |
| `otp` | string | no | OTP to verify the new secret |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns TOTP setup details when initiating the reset, or a verification result when confirming with an OTP. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_PASSWORD_COMPLEXITY_ERROR, ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TotpSetupInitiated):**

```json
{
  "username": "alice@example.com",
  "issuer": "kiteworks",
  "secret": "JBSWY3DPEHPK3PXP",
  "image": "data:image/png;base64,iVBOR..."
}
```

**200 (TotpSetupVerified):**

```json
{
  "code": 1
}
```

**422 (ERR_INPUT_PASSWORD_COMPLEXITY_ERROR):**

```json
{
  "errors": {
    "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR",
    "message": "Password does not meet complexity requirements"
  }
}
```

**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/users/me/tfa/resetTotpSecret" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "password": "string",
         "otp": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/tfa/resetTotpSecret"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "password": "string",
  "otp": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/users/me/tfa/setupTotpSecret

**Summary:** Setup secret key for Time-based OTP of the current user

Generates a new Time-based One-Time Password (TOTP) secret for the current user and returns the secret key along with a QR code for scanning with an authenticator app. Only available during the TFA setup login state and only if the user does not already have a TOTP secret registered.
**Responses:**

| Code | Description |
|------|-------------|
| 200 | TOTP secret setup initiated successfully. Returns the username, issuer, secret key, QR code image, and optional setup instructions. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TotpSetup):**

```json
{
  "username": "jane.doe@example.com",
  "issuer": "Kiteworks",
  "secret": "JBSWY3DPEHPK3PXP",
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..."
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/users/me/tfa/verifyTotpSecret

**Summary:** Verify code for finalising secret key for Time-based OTP

Verifies the one-time passcode generated by the user's authenticator app to confirm that the new TOTP secret was registered correctly. On success, advances the session to the next step in the authentication flow, skipping a redundant TFA step if one is pending.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `otp` | string | yes | OTP |
| `referral` | string | no | referral |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | TOTP secret verified successfully. Returns a redirectUrl string for the next step in the authentication flow. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TotpVerified):**

```json
{
  "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback"
}
```

**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/users/me/tfa/verifyTotpSecret" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "otp": "string",
         "referral": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/tfa/verifyTotpSecret"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "otp": "string",
  "referral": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## PUT /rest/users/me/tfaSetup

**Summary:** Setup 2FA settings

Sets the mobile number for the current user's two-factor authentication setup. Only valid when the user's login state is TFA setup. Returns a redirect URL pointing to the next step in the authentication flow.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `otp` | string | yes | OTP |
| `referral` | string | no | referral |
| `rememberDevice` | boolean | no | remember device |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | 2FA settings updated successfully. Returns a redirect URL for the next step in the authentication flow. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TfaSetup):**

```json
{
  "redirectUrl": "/rest/auth/login"
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/users/me/tfaSetup" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "otp": "string",
         "referral": "string",
         "rememberDevice": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/tfaSetup"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "otp": "string",
  "referral": "string",
  "rememberDevice": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/users/me/tos

**Summary:** Terms of Service

Returns the Terms of Service configuration for the currently authenticated user's profile, including the TOS content, acceptance text, and whether acceptance is required.
**Responses:**

| Code | Description |
|------|-------------|
| 200 | Terms of Service retrieved successfully. Returns the TOS type, content, acceptance text, occurrence, and whether acceptance is required. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TosData):**

```json
{
  "type": "html",
  "data": "<p>By using this service you agree to our terms.</p>",
  "acceptanceText": "I agree to the Terms of Service",
  "occurance": "always",
  "isRequired": true
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/users/me/tos

**Summary:** Terms of Service

Records the current user's acceptance or rejection of the Terms of Service. In the standard login flow, advances the session to the next authentication step and returns a redirect URL. In OTP login mode, returns an empty 200 response.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `accept` | boolean | yes | accept |
| `referral` | string | no | referral |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Terms of Service acceptance recorded successfully. Returns a redirectUrl string for the next step in the authentication flow. In OTP login mode, returns an empty response. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (TosAccepted):**

```json
{
  "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback"
}
```

**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/users/me/tos" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "accept": true,
         "referral": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/tos"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "accept": true,
  "referral": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/users/preauth

**Summary:** User login preauth

User login preauth.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `username` | string | yes | username |
| `referral` | string | no | referral |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Pre-authentication check completed successfully. Returns the next step in the login flow, either a redirect URL or a signal to show a password field. |
| 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 (ShowPasswordField):**

```json
{
  "username": "jane.doe@example.com",
  "redirectUrl": null,
  "type": "password",
  "otp": false
}
```

**200 (SsoRedirect):**

```json
{
  "username": "jane.doe@corp.com",
  "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/sso/login?idp=corp",
  "type": "redirect",
  "otp": false
}
```

**200 (OtpRequired):**

```json
{
  "username": "jane.doe@example.com",
  "redirectUrl": null,
  "type": "password",
  "otp": true
}
```

**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 POST \
  "https://{instance}.kiteworks.com/rest/users/preauth" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "username": "string",
         "referral": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/preauth"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "username": "string",
  "referral": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/users/register

**Summary:** Register a User

Registers a new User in the system by specifying an email address and password.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `email` | string | yes | User's email |
| `password` | string | yes | Password |
| `link` | string | no | Ref link |
| `activationCode` | string | no | activation code |
| `redirect` | string | no | Special handling for redirect (sharedfiles) |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Registration initiated successfully. A notification email has been sent to the user depending on their account state. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_INVALID_EMAIL, ERR_INPUT_REQUIRED, ERR_INPUT_PASSWORD_COMPLEXITY_ERROR |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

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

**422 (ERR_INPUT_INVALID_EMAIL):**

```json
{
  "errors": {
    "code": "ERR_INPUT_INVALID_EMAIL",
    "message": "Input is not a valid email"
  }
}
```

**422 (ERR_INPUT_REQUIRED):**

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

**422 (ERR_INPUT_PASSWORD_COMPLEXITY_ERROR):**

```json
{
  "errors": {
    "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR",
    "message": "Password does not meet complexity requirements"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/register" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "email": "string",
         "password": "string",
         "link": "string",
         "activationCode": "string",
         "redirect": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/register"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "email": "string",
  "password": "string",
  "link": "string",
  "activationCode": "string",
  "redirect": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/users/requestPasswordReset

**Summary:** Request for password reset

Request for password reset of existing user
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `email` | string | yes | User's email |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Password reset request processed. A notification email may have been sent depending on the account state. Always returns 204 regardless of whether the email address exists. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_INVALID_EMAIL, ERR_INPUT_REQUIRED |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_USER):**

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

**422 (ERR_INPUT_INVALID_EMAIL):**

```json
{
  "errors": {
    "code": "ERR_INPUT_INVALID_EMAIL",
    "message": "Input is not a valid email"
  }
}
```

**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/users/requestPasswordReset" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "email": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/requestPasswordReset"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "email": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/users/resetPassword

**Summary:** Reset password

Reset password of an existing user
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `link` | string | yes | The password reset link |
| `password` | string | yes | Password |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | Password reset request processed. A notification email may have been sent depending on the account state. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED, ERR_INPUT_PASSWORD_COMPLEXITY_ERROR |
| 490 | Request blocked by WAF |

**Response Examples:**

**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"
  }
}
```

**422 (ERR_INPUT_PASSWORD_COMPLEXITY_ERROR):**

```json
{
  "errors": {
    "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR",
    "message": "Password does not meet complexity requirements"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/resetPassword" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "link": "string",
         "password": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/resetPassword"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "link": "string",
  "password": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/users/{id}/profileImage

**Summary:** Uploads a profile image

Uploads an image file to use as profile image

**Parameters:**

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

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `body` | string | yes | The binary content of the file. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Profile image uploaded successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (SettingsAfterUpload):**

```json
{
  "id": 42,
  "userId": 101,
  "languageId": 1,
  "storageUsed": 204800,
  "storageQuota": 1073741824,
  "profileIconId": 55,
  "mobileNumber": "+1-5551234567",
  "mobileNumberVerified": false
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/:id/profileImage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "body": "string"
       }'
```

**Python:**

```python
import requests

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

url = f"https://{{instance}}.kiteworks.com/rest/users/{id}/profileImage"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "body": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/users/{id}/profileImage

**Summary:** Deletes a profile image

Deletes the user's current profile image.

**Parameters:**

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

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Profile image deleted successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (SettingsAfterDelete):**

```json
{
  "id": 42,
  "userId": 101,
  "languageId": 1,
  "storageUsed": 204800,
  "storageQuota": 1073741824,
  "profileIconId": null,
  "mobileNumber": "+1-5551234567",
  "mobileNumberVerified": false
}
```

**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/users/:id/profileImage" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

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

url = f"https://{{instance}}.kiteworks.com/rest/users/{id}/profileImage"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```

---

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

**Summary:** Get User Settings

Returns the settings for the specified user, including language preference, location, email signature, storage usage, and mobile number. Users can only retrieve their own settings.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user to retrieve settings for |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | User settings returned successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (UserSettings):**

```json
{
  "languageId": 1,
  "locationId": 2,
  "signature": "<p>Best regards</p>",
  "storageUsed": 1048576,
  "storageQuota": 10737418240,
  "mobileNumber": "+14155550100",
  "mobileNumberVerified": true
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the user to retrieve settings for

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

---

## PUT /rest/users/{id}/settings

**Summary:** Update User Settings

Updates the settings for the specified user, including language preference, location, email signature, and timezone. Users can only update their own settings. Returns 400 if the location cannot be changed because it is managed by an LDAP/SSO mapping.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the user to update settings for |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `languageId` | integer | no | Language identifier for user settings |
| `locationId` | integer | no | Location identifier for user settings. User's personal default location for file send and uploads |
| `signature` | string | no | Email message signature |
| `mobileKeyStore` | string | no | Encrypted key store data used by the mobile client for secure operations |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | User settings updated successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (SettingsUpdated):**

```json
{
  "languageId": 2,
  "locationId": 3,
  "signature": "<p>Regards</p>",
  "storageUsed": 2097152,
  "storageQuota": 10737418240,
  "mobileNumber": "+14155550100",
  "mobileNumberVerified": true
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/users/:id/settings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "languageId": 1,
         "locationId": 1,
         "signature": "string",
         "mobileKeyStore": "string",
         "addLinks": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the user to update settings for

url = f"https://{{instance}}.kiteworks.com/rest/users/{id}/settings"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "languageId": 1,
  "locationId": 1,
  "signature": "string",
  "mobileKeyStore": "string",
  "addLinks": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/users/me/recent

**Summary:** Return user's recent items

### Description:
  Retrieves the current user's recently accessed files and folders.
### Precondition:
  The user profile must have "Collaboration Allowed" enabled.
### Response:
  Returns the list of the user's recently accessed items.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If true, includes the entity in the response body. |
| `with` | query | no | Specifies additional fields to include in the response. |
| `mode` | query | no | Determines the detail level of the response body. |
| `type` | query | no | Filter recent items by object type. Accepts a list of type values. `d` – Directories (folders) only. `f` – Files only. If omitted, both files and folders are returned. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Request successfully processed and recent items returned. |
| 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 GET \
  "https://{instance}.kiteworks.com/rest/users/me/recent" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

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

---

## POST /rest/users/me/recent

**Summary:** Add objects to user's recent items

### Description:
  Records one or more files or folders as recently accessed for the current user.
### Precondition:
  User must be authenticated.
### Response:
  The provided objects are added to the user's recent items list.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `objects` | RecentObject[] | yes | List of recently accessed objects to record, each containing an object UUID and last-accessed timestamp. |

**Responses:**

| Code | Description |
|------|-------------|
| 201 | All recent items were successfully recorded. |
| 207 | Some recent items were recorded successfully while others failed. |
| 400 | Bad Request  <i>Possible error codes: </i>ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**400 (ERR_REQUEST_INVALID_JSON):**

```json
{
  "errors": [
    {
      "code": "ERR_REQUEST_INVALID_JSON",
      "message": "Invalid json provided"
    }
  ]
}
```

**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"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

```json
{
  "errors": [
    {
      "code": "ERR_INVALID_PARAMETER",
      "message": "Invalid Parameter Exception"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/recent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "objects": [
         {
         "id": "string",
         "lastAccessed": "2024-01-15"
       }
       ]
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/recent"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "objects": [
  {
  "id": "string",
  "lastAccessed": "2024-01-15"
}
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/users/me/recent/{id}

**Summary:** Delete a user's recent item

### Description:
  Removes the specified object from the current user's recent items list.
### Precondition:
  User must be authenticated.
### Response:
  The item is removed from the user's recent items.

**Parameters:**

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

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The recent item was successfully removed. |
| 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/users/me/recent/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

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

url = f"https://{{instance}}.kiteworks.com/rest/users/me/recent/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
```

---

## POST /rest/users/me/pins

**Summary:** Pin items for the current user

### Description:
  Pins the specified entities to the current user's pinned list.
### Precondition:
  User must be authenticated.
### Response:
  The specified items are pinned.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | yes | List of entity IDs to pin or unpin. |
| `type` | string | yes | The type of entity being pinned or unpinned. `source` – An external content source. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The items were successfully pinned. |
| 400 | Bad Request  <i>Possible error codes: </i>ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**400 (ERR_REQUEST_INVALID_JSON):**

```json
{
  "errors": [
    {
      "code": "ERR_REQUEST_INVALID_JSON",
      "message": "Invalid json provided"
    }
  ]
}
```

**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"
    }
  ]
}
```

**403 (ERR_ACCESS_USER):**

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

**422 (ERR_INVALID_PARAMETER):**

```json
{
  "errors": [
    {
      "code": "ERR_INVALID_PARAMETER",
      "message": "Invalid Parameter Exception"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/pins" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "ids": [
         "string"
       ],
         "type": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/pins"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "ids": [
  "string"
],
  "type": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/users/me/pins

**Summary:** Unpin items for the current user

### Description:
  Removes the specified entities from the current user's pinned list.
### Precondition:
  User must be authenticated.
### Response:
  The specified items are unpinned.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | yes | List of entity IDs to pin or unpin. |
| `type` | string | yes | The type of entity being pinned or unpinned. `source` – An external content source. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The items were successfully unpinned. |
| 400 | Bad Request  <i>Possible error codes: </i>ERR_REQUEST_INVALID_JSON |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INVALID_PARAMETER |
| 490 | Request blocked by WAF |

**Response Examples:**

**400 (ERR_REQUEST_INVALID_JSON):**

```json
{
  "errors": [
    {
      "code": "ERR_REQUEST_INVALID_JSON",
      "message": "Invalid json provided"
    }
  ]
}
```

**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"
    }
  ]
}
```

**422 (ERR_INVALID_PARAMETER):**

```json
{
  "errors": [
    {
      "code": "ERR_INVALID_PARAMETER",
      "message": "Invalid Parameter Exception"
    }
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## GET /rest/users/actions/getDistributionList

**Summary:** Check emails for LDAP distribution list status

### Description:
  Checks whether the provided email addresses correspond to LDAP distribution lists rather than individual users.
### Precondition:
  User must be authenticated.
### Response:
  Returns each email address along with a flag indicating whether it is an LDAP distribution list.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `email:in` | query | yes | Comma-separated list of email addresses to check for LDAP distribution list status. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The distribution list status for each email has been successfully returned. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_DENIED, ERR_ACCESS_USER |
| 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"
    }
  ]
}
```

**403 (ERR_ACCESS_DENIED):**

```json
{
  "errors": [
    {
      "code": "ERR_ACCESS_DENIED",
      "message": "Your access is denied.",
      "redirectUrl": "/login?code=3317"
    }
  ]
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

```shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/actions/getDistributionList?email:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/actions/getDistributionList"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
params = {
    "email:in": "VALUE",
}
response = requests.get(url, params=params, headers=headers)
print(response.json())
```

---

## GET /rest/users/me/concurrent/challenge

**Summary:** Get concurrent session challenge

### Description:
  Returns information about the existing concurrent session that must be resolved before the current login can proceed.
### Precondition:
  User must be in the `concurrent` login state.
### Response:
  Returns the concurrent session details required to complete the challenge.
**Responses:**

| Code | Description |
|------|-------------|
| 200 | The concurrent session challenge details have been successfully returned. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_AUTH_WRONG_LOGIN_STATE, ERR_CONCURRENT_NOT_FOUND |
| 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"
    }
  ]
}
```

**403 (ERR_AUTH_WRONG_LOGIN_STATE):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_WRONG_LOGIN_STATE",
      "message": "Wrong login state"
    }
  ]
}
```

**403 (ERR_CONCURRENT_NOT_FOUND):**

```json
{
  "errors": [
    {
      "code": "ERR_CONCURRENT_NOT_FOUND",
      "message": "Concurrent session does not exist"
    }
  ]
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/users/me/concurrent/auth

**Summary:** Resolve a concurrent session challenge

### Description:
  Resolves a concurrent login challenge by either terminating the existing session or cancelling the current login attempt.
### Precondition:
  User must be in the `concurrent` login state.
### Response:
  Returns the login result after the concurrent session challenge is resolved.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `terminate` | boolean | yes | If true, terminates the existing concurrent session and proceeds with the current login. If false, cancels the current login attempt. |
| `referral` | string | yes | The referral token from the concurrent session challenge, used to identify the session to terminate. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The concurrent session challenge was successfully resolved. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_AUTH_WRONG_LOGIN_STATE |
| 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"
    }
  ]
}
```

**403 (ERR_AUTH_WRONG_LOGIN_STATE):**

```json
{
  "errors": [
    {
      "code": "ERR_AUTH_WRONG_LOGIN_STATE",
      "message": "Wrong login state"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/concurrent/auth" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "terminate": true,
         "referral": "string"
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/users/me/concurrent/auth"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "terminate": true,
  "referral": "string"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/admin/users/actions/import

**Summary:** Bulk import users via CSV file

### Overview:
  Import users in bulk using a CSV file.
### Precondition:
  The user must be an administrator with access to `User Management`.
### Response:
  The users will be either created or updated.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `content` | string | yes | The CSV file containing the users to be imported. |
| `updateIfExists` | boolean | no | If true, existing users will be updated with the new settings. |
| `sendNotification` | boolean | no | If true, a notification email will be sent to each newly created user. |
| `partialSuccess` | boolean | no | If true, only validated users will be imported, while others will be rejected. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Users have been successfully imported. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_ADMIN |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_INVALID_FORMAT, ERR_INVALID_ARGUMENT |
| 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"
    }
  ]
}
```

**403 (ERR_ACCESS_ADMIN):**

```json
{
  "errors": [
    {
      "code": "ERR_ACCESS_ADMIN",
      "message": "Insufficient admin access permissions"
    }
  ]
}
```

**422 (ERR_INPUT_INVALID_FORMAT):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_INVALID_FORMAT",
      "message": "The input is invalid."
    }
  ]
}
```

**422 (ERR_INVALID_ARGUMENT):**

```json
{
  "errors": [
    {
      "code": "ERR_INVALID_ARGUMENT",
      "message": "Invalid Argument"
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/admin/users/actions/import" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "content": "string",
         "updateIfExists": true,
         "sendNotification": true,
         "partialSuccess": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/users/actions/import"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "content": "string",
  "updateIfExists": true,
  "sendNotification": true,
  "partialSuccess": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## POST /rest/admin/users/actions/deleteTotpSecret

**Summary:** Delete TOTP secrets for users

### Description:
  Deletes the TOTP (Time-based One-Time Password) secret for the specified users.
### Precondition:
  The user must be an administrator. The caller's admin role rank must be sufficient to manage the target users.
### Response:
  The TOTP secrets for the specified users are deleted successfully.
**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `ids` | string[] | yes | List of user UUIDs whose TOTP secrets should be deleted. Must contain between 1 and 100 IDs. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | The TOTP secrets were deleted successfully. |
| 401 | Unauthorized  <i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_ADMIN, ERR_ACCESS_USER, ERR_ADMIN_ROLE_RANK_RESTRICTED |
| 404 | Not Found  <i>Possible error codes: </i>ERR_ENTITY_NOT_FOUND |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_INVALID_FORMAT |
| 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"
    }
  ]
}
```

**403 (ERR_ACCESS_ADMIN):**

```json
{
  "errors": [
    {
      "code": "ERR_ACCESS_ADMIN",
      "message": "Insufficient admin access permissions"
    }
  ]
}
```

**403 (ERR_ACCESS_USER):**

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

**403 (ERR_ADMIN_ROLE_RANK_RESTRICTED):**

```json
{
  "errors": [
    {
      "code": "ERR_ADMIN_ROLE_RANK_RESTRICTED",
      "message": "Action is restricted due to admin role rank"
    }
  ]
}
```

**404 (ERR_ENTITY_NOT_FOUND):**

```json
{
  "errors": [
    {
      "code": "ERR_ENTITY_NOT_FOUND",
      "message": "Entity does not exist"
    }
  ]
}
```

**422 (ERR_INPUT_INVALID_FORMAT):**

```json
{
  "errors": [
    {
      "code": "ERR_INPUT_INVALID_FORMAT",
      "message": "The input is invalid."
    }
  ]
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/admin/users/actions/deleteTotpSecret" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "ids": [
         "string"
       ]
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/admin/users/actions/deleteTotpSecret"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "ids": [
  "string"
]
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---