users

36 endpoints
DELETE/rest/users

Deletes Users

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

Parameters
Query Parameters
id:in
Required
string

List of user IDs to delete.

retainToUser
Optional
string

The ID of the new owner to whom the data will be transferred, applicable when retainData and/or retainPermissionToSharedData are set to true.

retainToAdvancedFormUser
Optional
string

The ID of the user to whom the advanced form data will be transferred, similar to retainToUser but specifically for advanced form components.

remoteWipe
Optional
boolean

Indicates whether to remotely wipe data from both desktop and mobile devices.

deleteUnsharedData
Optional
boolean

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
Optional
boolean

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
Optional
boolean

Indicates whether permissions to shared folders should be retained.

withdrawFileLinks
Optional
boolean

Indicates whether files sent by deleted or demoted users should be withdrawn.

withdrawRequestFiles
Optional
boolean

Indicates whether request files sent by deleted or demoted users should be withdrawn.

partialSuccess
Optional
boolean

If set to true, the operation will continue for the valid items even if some items result in failure.

mode
Optional
string

Determines the detail level of the response body.


Responses

Specified users marked as deleted.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_NOT_BOOLEAN, ERR_INPUT_ATTRIBUTE_FORBIDDEN, ERR_INPUT_REQUIRED, ERR_INPUT_NOT_STRING

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/users?id:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
// Request successful - No Body
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
{ "errors": { "code": "ERR_INPUT_NOT_BOOLEAN", "message": "Input is not a valid boolean" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
POST/rest/users/actions/login

User login

Handles user login by accepting the user credentials (username and password).

Request Body
username
Required
string

The username of the user attempting to log in.

password
Required
string

The password of the user. It must be kept confidential and securely stored.

referral
string

The URL that referred the user to this login action.


Responses

Login successful. Returns a redirect URL and success status.

success
boolean

Indicates whether the login was successful. Always true on a successful response.

redirectUrl
string

The URL to redirect to for the next step in the authentication flow.

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/actions/login" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "username": "string",
         "password": "string",
         "referral": "string"
       }'
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())
Responses
{ "success": true, "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback" }
{ "success": false, "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/tfa" }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
PUT/rest/users/aliveToken

Updates token state

Updates current session state to be not outdated any more

This endpoint requires no parameters.

Responses

Token state updated successfully

Empty response body.

Request blocked by WAF

Empty response body.
Shell
curl -X PUT \
  "https://{instance}.kiteworks.com/rest/users/aliveToken" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
// Request successful - No Body
// Error - No Body
GET/rest/users/ldapSearch

Find users in LDAP by input supplied

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

Parameters
Query Parameters
value
Required
string

The user's email or name

with
Optional
string

With parameters

mode
Optional
string

Determines the detail level of the response body.


Responses

Returns users found in LDAP matching the supplied search criteria.

email
string

User's email

displayName
string

Users's display name

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/ldapSearch?value=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "matches": [ { "email": "jane.doe@example.com", "displayName": "Jane Doe" }, { "email": "john.smith@example.com", "displayName": "John Smith" } ] }
// Error - No Body
GET/rest/users/me

Retrieve details of the currently logged-in user

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

This endpoint requires no parameters.

Responses

Returns the details of the currently authenticated user.

id
Required
string

The unique identifier of the user

basedirId
Required
string

The unique identifier of the user's root Kiteworks directory.

created
string

Date and time the user account was created

email
Required
string

The user's email

mydirId
Required
string

The unique identifier of the user's mydir system directory.

name
Required
string

The name of the user

syncdirId
Required
string

The unique identifier of the user's 'My Folder'.

userTypeId
integer

The unique identifier of the user type (profile).

internal
boolean

Indicates whether the user is an internal user

profileIcon
string

URL to the user's profile icon image

extDL
boolean

Indicates whether the user is an External Distribution List

name
string

Key name of the custom metadata attribute associated with the user

value
string

Value assigned to the custom metadata attribute for the user

adminRoleId
integer

The ID of the admin role assigned to the user.

links
string[]

HATEOAS links associated with the entity

serviceName
string

Name of the Kiteworks service instance the user is connected to

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/me" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "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" }
// Error - No Body
PUT/rest/users/me

Update the current user's details

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

Request Body
password
string

The user's password

previousPassword
string

The user's previous password

name
string

The user's name


Responses

Currently authenticated user details updated successfully. Returns the updated user object.

id
Required
string

The unique identifier of the user

basedirId
Required
string

The unique identifier of the user's root Kiteworks directory.

created
string

Date and time the user account was created

email
Required
string

The user's email

mydirId
Required
string

The unique identifier of the user's mydir system directory.

name
Required
string

The name of the user

syncdirId
Required
string

The unique identifier of the user's 'My Folder'.

userTypeId
integer

The unique identifier of the user type (profile).

internal
boolean

Indicates whether the user is an internal user

profileIcon
string

URL to the user's profile icon image

extDL
boolean

Indicates whether the user is an External Distribution List

name
string

Key name of the custom metadata attribute associated with the user

value
string

Value assigned to the custom metadata attribute for the user

adminRoleId
integer

The ID of the admin role assigned to the user.

links
string[]

HATEOAS links associated with the entity

serviceName
string

Name of the Kiteworks service instance the user is connected to

Unprocessable Content

Possible error codes: ERR_INPUT_PASSWORD_COMPLEXITY_ERROR

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
{ "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" }
{ "errors": { "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR", "message": "Password does not meet complexity requirements" } }
// Error - No Body
POST/rest/users/me/forcedPasswordChange

Change the password for current user after expired

Change the password for current user after password expired

Request Body
password
string

The user's password

previousPassword
string

The user's previous password

referral
string

referral


Responses

Password changed successfully. Returns a redirect URL for the next step in the authentication flow.

redirectUrl
string

The URL to redirect to for the next step in the flow.

Unprocessable Content

Possible error codes: ERR_INPUT_PASSWORD_COMPLEXITY_ERROR, ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/forcedPasswordChange" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "password": "string",
         "previousPassword": "string",
         "referral": "string"
       }'
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())
Responses
{ "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback" }
{ "errors": { "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR", "message": "Password does not meet complexity requirements" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
PUT/rest/users/me/mobileNumber

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
password
Required
string

The current password of the user

mobileNumber
Required
string

The user's new mobile number

testOnly
boolean

If true, a short message will be sent to the number, and the number will not be saved


Responses

Mobile number updated successfully. Returns the updated user settings.

languageId
integer

Language identifier of the user the settings represent

locationId
integer

Location identifier for user settings. User's personal default location for file send and uploads

signature
string

Email message signature

storageUsed
integer

Storage used by the user across the folders they own

storageQuota
integer

Storage quota allocated to the user across all the folders they own

mobileKeyStore
string

Encrypted key store data used by the mobile client for secure operations

mobileNumber
string

User's mobile number

mobileNumberVerified
boolean

Indicates whether the mobile number is verified

links
string[]

HATEOAS links associated with the entity

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED, ERR_INPUT_INVALID_FORMAT

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
{ "languageId": 1, "locationId": 2, "signature": "", "storageUsed": 1048576, "storageQuota": 10737418240, "mobileNumber": "+14155550199", "mobileNumberVerified": false }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
GET/rest/users/me/quota

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
Query Parameters
filter
Optional
string

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

The user quota is successfully retrieved.

send_quota_allowed
integer

The allowed send quota for the user.

send_quota_used
integer

The amount of send quota used by the user.

folder_quota_allowed
integer

The allowed folder quota for the user.

folder_quota_used
integer

The amount of folder quota used by the user.

current_num_sys_folders
integer

Current number of system folders.

max_num_sys_folders
integer

Maximum allowed number of system folders.

per_folder_quota_options
integer[]

List of available quota options per folder.

per_folder_default_quota
integer

Default quota assigned to each folder.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Not Found

Possible error codes: ERR_ENTITY_NOT_FOUND

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/me/quota" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "send_quota_allowed": 1, "send_quota_used": 1, "folder_quota_allowed": 1, "folder_quota_used": 1, "sys_folders": {} }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ENTITY_NOT_FOUND", "message": "Entity does not exist" } ] }
// Error - No Body
POST/rest/users/me/tfa/auth

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
otp
Required
string

OTP

referral
string

referral

rememberDevice
boolean

remember device


Responses

Two Factor Authentication completed. Returns either a redirectUrl string on success or a challengeMsg string if an additional challenge is required.

redirectUrl
string

The URL to redirect to for the next step in the authentication flow. Present when TFA is accepted; mutually exclusive with challengeMsg.

challengeMsg
string

A message from the TFA module to display to the user (for example, instructions to check their phone). Present when a challenge is in progress; mutually exclusive with redirectUrl.

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/tfa/auth" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "otp": "string",
         "referral": "string",
         "rememberDevice": true
       }'
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())
Responses
{ "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback" }
{ "challengeMsg": "Incorrect passcode. Please try again." }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
POST/rest/users/me/tfa/challenge

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
Query Parameters
referral
Optional
string

Referral URL


Responses

Two Factor Authentication challenge initiated successfully. Returns either a challengeMsg string or a redirectUrl string depending on the authentication flow.

redirectUrl
string

The URL to redirect to for the next step in the authentication flow. Present when TFA is accepted; mutually exclusive with challengeMsg.

challengeMsg
string

A message from the TFA module to display to the user (for example, instructions to check their phone). Present when a challenge is in progress; mutually exclusive with redirectUrl.

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/tfa/challenge" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "challengeMsg": "A passcode has been sent to your mobile device." }
{ "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback" }
// Error - No Body
GET/rest/users/me/tfa/config

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.

This endpoint requires no parameters.

Responses

Two Factor Authentication configuration retrieved successfully.

module
string

The name of the active Two-Factor Authentication (TFA) module.

passcodeLabel
string

The label to display for the passcode input field.

passcodeDescription
string

A description of the passcode input field.

rechallengeLabel
string

The label for the rechallenge action.

challengeShouldSendPassword
boolean

Indicates whether the password should be sent along with the challenge request.

challengeWaitMessage
string

A message to display to the user while waiting for the challenge response.

rechallengeMessage
string

A message to display when prompting the user to rechallenge.

rememberDeviceEnabled
boolean

Indicates whether the remember device feature is enabled for this user.

passcodeMask
boolean

Indicates whether the passcode input should be masked.

mobileNumber
string

The user's mobile number. Present only when the TFA module is SMSOTP.

allowNumberChange
boolean

Indicates whether the user is allowed to change their mobile number. Present only when the TFA module is SMSOTP.

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/me/tfa/config" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "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 }
{ "module": "TOTP", "passcodeLabel": "Authenticator code", "passcodeDescription": "Enter the 6-digit code from your authenticator app.", "rechallengeLabel": "", "challengeShouldSendPassword": false, "challengeWaitMessage": "", "rechallengeMessage": "", "rememberDeviceEnabled": true, "passcodeMask": false }
// Error - No Body
POST/rest/users/me/tfa/resetTotpSecret

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
password
Required
string

The user's password

otp
string

OTP to verify the new secret


Responses

Returns TOTP setup details when initiating the reset, or a verification result when confirming with an OTP.

username
string

The username associated with the TOTP secret.

issuer
string

The issuer name used in the TOTP URI, typically the server hostname.

secret
string

The base32-encoded TOTP secret key to be stored in the authenticator app.

image
string

A base64-encoded QR code image encoding the TOTP URI for scanning with an authenticator app.

setup_instruction_1
string

Optional first setup instruction. Only present when provided by the authentication backend.

setup_instruction_2
string

Optional second setup instruction. Only present when provided by the authentication backend.

Unprocessable Content

Possible error codes: ERR_INPUT_PASSWORD_COMPLEXITY_ERROR, ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/tfa/resetTotpSecret" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "password": "string",
         "otp": "string"
       }'
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())
Responses
{ "username": "alice@example.com", "issuer": "kiteworks", "secret": "JBSWY3DPEHPK3PXP", "image": "data:image/png;base64,iVBOR..." }
{ "code": 1 }
{ "errors": { "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR", "message": "Password does not meet complexity requirements" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
GET/rest/users/me/tfa/setupTotpSecret

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.

This endpoint requires no parameters.

Responses

TOTP secret setup initiated successfully. Returns the username, issuer, secret key, QR code image, and optional setup instructions.

username
string

The username associated with the TOTP secret.

issuer
string

The issuer name used in the TOTP URI, typically the server hostname.

secret
string

The base32-encoded TOTP secret key to be stored in the authenticator app.

image
string

A base64-encoded QR code image encoding the TOTP URI for scanning with an authenticator app.

setup_instruction_1
string

Optional first setup instruction. Only present when provided by the authentication backend.

setup_instruction_2
string

Optional second setup instruction. Only present when provided by the authentication backend.

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/me/tfa/setupTotpSecret" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "username": "jane.doe@example.com", "issuer": "Kiteworks", "secret": "JBSWY3DPEHPK3PXP", "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA..." }
// Error - No Body
POST/rest/users/me/tfa/verifyTotpSecret

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
otp
Required
string

OTP

referral
string

referral


Responses

TOTP secret verified successfully. Returns a redirectUrl string for the next step in the authentication flow.

redirectUrl
string

The URL to redirect to for the next step in the flow.

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/tfa/verifyTotpSecret" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "otp": "string",
         "referral": "string"
       }'
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())
Responses
{ "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback" }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
PUT/rest/users/me/tfaSetup

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
otp
Required
string

OTP

referral
string

referral

rememberDevice
boolean

remember device


Responses

2FA settings updated successfully. Returns a redirect URL for the next step in the authentication flow.

redirectUrl
string

The URL to redirect to for the next step in the flow.

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X 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
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())
Responses
{ "redirectUrl": "/rest/auth/login" }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
GET/rest/users/me/tos

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.

This endpoint requires no parameters.

Responses

Terms of Service retrieved successfully. Returns the TOS type, content, acceptance text, occurrence, and whether acceptance is required.

type
string

The type of Terms of Service.

data
string

The full Terms of Service content.

acceptanceText
string

The text to display on the acceptance button or checkbox.

occurrence
string

How often the Terms of Service is shown to the user.

isRequired
boolean

Indicates whether the user is required to accept the Terms of Service.

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/me/tos" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "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 }
// Error - No Body
POST/rest/users/me/tos

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
accept
Required
boolean

accept

referral
string

referral


Responses

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.

redirectUrl
string

The URL to redirect to for the next step in the flow.

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/me/tos" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "accept": true,
         "referral": "string"
       }'
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())
Responses
{ "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/auth/callback" }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
POST/rest/users/preauth

User login preauth

User login preauth.

Request Body
username
Required
string

username

referral
string

referral


Responses

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.

username
string

The username used for preauth.

redirectUrl
string

The URL to redirect to. Present when type is redirect, null when type is password.

type
string

The next step in the login flow. Accepted values: password (show a password field), redirect (redirect the user to redirectUrl).

otp
boolean

Whether the login flow requires OTP authentication.

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/preauth" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "username": "string",
         "referral": "string"
       }'
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())
Responses
{ "username": "jane.doe@example.com", "redirectUrl": null, "type": "password", "otp": false }
{ "username": "jane.doe@corp.com", "redirectUrl": "https://<YOUR_INSTANCE_DOMAIN>/sso/login?idp=corp", "type": "redirect", "otp": false }
{ "username": "jane.doe@example.com", "redirectUrl": null, "type": "password", "otp": true }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
POST/rest/users/register

Register a User

Registers a new User in the system by specifying an email address and password.

Request Body
email
Required
string

User's email

password
Required
string

Password

link
string

Ref link

activationCode
string

activation code

redirect
string

Special handling for redirect (sharedfiles)


Responses

Registration initiated successfully. A notification email has been sent to the user depending on their account state.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_INVALID_EMAIL, ERR_INPUT_REQUIRED, ERR_INPUT_PASSWORD_COMPLEXITY_ERROR

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
// Request successful - No Body
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
{ "errors": { "code": "ERR_INPUT_INVALID_EMAIL", "message": "Input is not a valid email" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
{ "errors": { "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR", "message": "Password does not meet complexity requirements" } }
// Error - No Body
POST/rest/users/requestPasswordReset

Request for password reset

Request for password reset of existing user

Request Body
email
Required
string

User's email


Responses

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.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_INVALID_EMAIL, ERR_INPUT_REQUIRED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/requestPasswordReset" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "email": "string"
       }'
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())
Responses
// Request successful - No Body
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
{ "errors": { "code": "ERR_INPUT_INVALID_EMAIL", "message": "Input is not a valid email" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
// Error - No Body
POST/rest/users/resetPassword

Reset password

Reset password of an existing user

Request Body
link
Required
string

The password reset link

password
Required
string

Password


Responses

Password reset request processed. A notification email may have been sent depending on the account state.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_REQUIRED, ERR_INPUT_PASSWORD_COMPLEXITY_ERROR

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
// Request successful - No Body
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
{ "errors": { "code": "ERR_INPUT_REQUIRED", "message": "Field is required" } }
{ "errors": { "code": "ERR_INPUT_PASSWORD_COMPLEXITY_ERROR", "message": "Password does not meet complexity requirements" } }
// Error - No Body
POST/rest/users/{id}/profileImage

Uploads a profile image

Uploads an image file to use as profile image

Parameters
Path Parameters
id
Required
string

The unique identifier of the user.


Request Body
body
Required
string

The binary content of the file.


Responses

Profile image uploaded successfully.

languageId
integer

Language identifier of the user the settings represent

locationId
integer

Location identifier for user settings. User's personal default location for file send and uploads

signature
string

Email message signature

storageUsed
integer

Storage used by the user across the folders they own

storageQuota
integer

Storage quota allocated to the user across all the folders they own

mobileKeyStore
string

Encrypted key store data used by the mobile client for secure operations

mobileNumber
string

User's mobile number

mobileNumberVerified
boolean

Indicates whether the mobile number is verified

links
string[]

HATEOAS links associated with the entity

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/users/:id/profileImage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "body": "string"
       }'
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())
Responses
{ "id": 42, "userId": 101, "languageId": 1, "storageUsed": 204800, "storageQuota": 1073741824, "profileIconId": 55, "mobileNumber": "+1-5551234567", "mobileNumberVerified": false }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
DELETE/rest/users/{id}/profileImage

Deletes a profile image

Deletes the user's current profile image.

Parameters
Path Parameters
id
Required
string

The unique identifier of the user.


Responses

Profile image deleted successfully.

languageId
integer

Language identifier of the user the settings represent

locationId
integer

Location identifier for user settings. User's personal default location for file send and uploads

signature
string

Email message signature

storageUsed
integer

Storage used by the user across the folders they own

storageQuota
integer

Storage quota allocated to the user across all the folders they own

mobileKeyStore
string

Encrypted key store data used by the mobile client for secure operations

mobileNumber
string

User's mobile number

mobileNumberVerified
boolean

Indicates whether the mobile number is verified

links
string[]

HATEOAS links associated with the entity

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/users/:id/profileImage" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "id": 42, "userId": 101, "languageId": 1, "storageUsed": 204800, "storageQuota": 1073741824, "profileIconId": null, "mobileNumber": "+1-5551234567", "mobileNumberVerified": false }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
GET/rest/users/{id}/settings

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
Path Parameters
id
Required
string

ID of the user to retrieve settings for


Responses

User settings returned successfully.

languageId
integer

Language identifier of the user the settings represent

locationId
integer

Location identifier for user settings. User's personal default location for file send and uploads

signature
string

Email message signature

storageUsed
integer

Storage used by the user across the folders they own

storageQuota
integer

Storage quota allocated to the user across all the folders they own

mobileKeyStore
string

Encrypted key store data used by the mobile client for secure operations

mobileNumber
string

User's mobile number

mobileNumberVerified
boolean

Indicates whether the mobile number is verified

links
string[]

HATEOAS links associated with the entity

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/:id/settings" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "languageId": 1, "locationId": 2, "signature": "<p>Best regards</p>", "storageUsed": 1048576, "storageQuota": 10737418240, "mobileNumber": "+14155550100", "mobileNumberVerified": true }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
PUT/rest/users/{id}/settings

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
Path Parameters
id
Required
string

ID of the user to update settings for


Request Body
languageId
integer

Language identifier for user settings

locationId
integer

Location identifier for user settings. User's personal default location for file send and uploads

signature
string

Email message signature

mobileKeyStore
string

Encrypted key store data used by the mobile client for secure operations

addLinks
boolean

Indicates whether HATEOAS links should be included in the response


Responses

User settings updated successfully.

languageId
integer

Language identifier of the user the settings represent

locationId
integer

Location identifier for user settings. User's personal default location for file send and uploads

signature
string

Email message signature

storageUsed
integer

Storage used by the user across the folders they own

storageQuota
integer

Storage quota allocated to the user across all the folders they own

mobileKeyStore
string

Encrypted key store data used by the mobile client for secure operations

mobileNumber
string

User's mobile number

mobileNumberVerified
boolean

Indicates whether the mobile number is verified

links
string[]

HATEOAS links associated with the entity

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X 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
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())
Responses
{ "languageId": 2, "locationId": 3, "signature": "<p>Regards</p>", "storageUsed": 2097152, "storageQuota": 10737418240, "mobileNumber": "+14155550100", "mobileNumberVerified": true }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
GET/rest/users/me/recent

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
Query Parameters
returnEntity
Optional
boolean

If true, includes the entity in the response body.

with
Optional
string

Specifies additional fields to include in the response.

mode
Optional
string

Determines the detail level of the response body.

type
Optional
string[]

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

Request successfully processed and recent items returned.

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/me/recent" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
[ {} ]
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
// Error - No Body
POST/rest/users/me/recent

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
objects
Required
RecentObject[]

List of recently accessed objects to record, each containing an object UUID and last-accessed timestamp.


Responses

All recent items were successfully recorded.

Empty response body.

Some recent items were recorded successfully while others failed.

Empty response body.

Bad Request

Possible error codes: ERR_REQUEST_INVALID_JSON

code
string

Error code

message
string

Error message

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
// Request successful - No Body
// Request successful - No Body
{ "errors": [ { "code": "ERR_REQUEST_INVALID_JSON", "message": "Invalid json provided" } ] }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
// Error - No Body
DELETE/rest/users/me/recent/{id}

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
Path Parameters
id
Required
integer

The unique identifier of the entity.


Responses

The recent item was successfully removed.

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/users/me/recent/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
// Error - No Body
POST/rest/users/me/pins

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
ids
Required
string[]

List of entity IDs to pin or unpin.

type
Required
string

The type of entity being pinned or unpinned.
source – An external content source.


Responses

The items were successfully pinned.

Empty response body.

Bad Request

Possible error codes: ERR_REQUEST_INVALID_JSON

code
string

Error code

message
string

Error message

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_REQUEST_INVALID_JSON", "message": "Invalid json provided" } ] }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
// Error - No Body
DELETE/rest/users/me/pins

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
ids
Required
string[]

List of entity IDs to pin or unpin.

type
Required
string

The type of entity being pinned or unpinned.
source – An external content source.


Responses

The items were successfully unpinned.

Empty response body.

Bad Request

Possible error codes: ERR_REQUEST_INVALID_JSON

code
string

Error code

message
string

Error message

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INVALID_PARAMETER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X DELETE \
  "https://{instance}.kiteworks.com/rest/users/me/pins" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_REQUEST_INVALID_JSON", "message": "Invalid json provided" } ] }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_INVALID_PARAMETER", "message": "Invalid Parameter Exception" } ] }
// Error - No Body
GET/rest/users/actions/getDistributionList

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
Query Parameters
email:in
Required
string[]

Comma-separated list of email addresses to check for LDAP distribution list status.


Responses

The distribution list status for each email has been successfully returned.

email
string

Email address of the distribution list or individual contact.

isDl
boolean

Indicates whether the entry is a distribution list.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_DENIED, ERR_ACCESS_USER

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/actions/getDistributionList?email:in=VALUE" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "data": [ { "email": "string", "isDl": true } ] }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_DENIED", "message": "Your access is denied.", "redirectUrl": "/login?code=3317" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
// Error - No Body
GET/rest/users/me/concurrent/challenge

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.
This endpoint requires no parameters.

Responses

The concurrent session challenge details have been successfully returned.

created
string
userAgent
string
location
string

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_AUTH_WRONG_LOGIN_STATE, ERR_CONCURRENT_NOT_FOUND

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/users/me/concurrent/challenge" \
  -H "Authorization: Bearer YOUR_TOKEN"
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())
Responses
{ "created": "2024-01-15", "userAgent": "string", "location": "string" }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_AUTH_WRONG_LOGIN_STATE", "message": "Wrong login state" } ] }
{ "errors": [ { "code": "ERR_CONCURRENT_NOT_FOUND", "message": "Concurrent session does not exist" } ] }
// Error - No Body
POST/rest/users/me/concurrent/auth

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
terminate
Required
boolean

If true, terminates the existing concurrent session and proceeds with the current login. If false, cancels the current login attempt.

referral
Required
string

The referral token from the concurrent session challenge, used to identify the session to terminate.


Responses

The concurrent session challenge was successfully resolved.

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_AUTH_WRONG_LOGIN_STATE

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_AUTH_WRONG_LOGIN_STATE", "message": "Wrong login state" } ] }
// Error - No Body
POST/rest/admin/users/actions/import

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
content
Required
string

The CSV file containing the users to be imported.

updateIfExists
boolean

If true, existing users will be updated with the new settings.

sendNotification
boolean

If true, a notification email will be sent to each newly created user.

partialSuccess
boolean

If true, only validated users will be imported, while others will be rejected.


Responses

Users have been successfully imported.

added_users
integer

Number of users successfully added.

updated_users
integer

Number of users successfully updated.

failed_ids
string[]

List of user emails that failed during import.

id
string

Unique identifier for the error.

message
string

Description of the error.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_ADMIN

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_INVALID_FORMAT, ERR_INVALID_ARGUMENT

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
{ "added_users": 1, "updated_users": 1, "failed_ids": [ "string" ], "errors": [ { "id": "string", "message": "string" } ] }
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_ADMIN", "message": "Insufficient admin access permissions" } ] }
{ "errors": [ { "code": "ERR_INPUT_INVALID_FORMAT", "message": "The input is invalid." } ] }
{ "errors": [ { "code": "ERR_INVALID_ARGUMENT", "message": "Invalid Argument" } ] }
// Error - No Body
POST/rest/admin/users/actions/deleteTotpSecret

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
ids
Required
string[]

List of user UUIDs whose TOTP secrets should be deleted. Must contain between 1 and 100 IDs.


Responses

The TOTP secrets were deleted successfully.

Empty response body.

Unauthorized

Possible error codes: ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED

code
string

Error code

message
string

Error message

Forbidden

Possible error codes: ERR_ACCESS_ADMIN, ERR_ACCESS_USER, ERR_ADMIN_ROLE_RANK_RESTRICTED

code
string

Error code

message
string

Error message

Not Found

Possible error codes: ERR_ENTITY_NOT_FOUND

code
string

Error code

message
string

Error message

Unprocessable Content

Possible error codes: ERR_INPUT_INVALID_FORMAT

code
string

Error code

message
string

Error message

Request blocked by WAF

Empty response body.
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
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())
Responses
// Request successful - No Body
{ "errors": [ { "code": "ERR_AUTH_INVALID_CSRF", "message": "Invalid CSRF Authentication" } ] }
{ "errors": [ { "code": "ERR_AUTH_UNAUTHORIZED", "message": "Unauthorized" } ] }
{ "errors": [ { "code": "ERR_ACCESS_ADMIN", "message": "Insufficient admin access permissions" } ] }
{ "errors": [ { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } ] }
{ "errors": [ { "code": "ERR_ADMIN_ROLE_RANK_RESTRICTED", "message": "Action is restricted due to admin role rank" } ] }
{ "errors": [ { "code": "ERR_ENTITY_NOT_FOUND", "message": "Entity does not exist" } ] }
{ "errors": [ { "code": "ERR_INPUT_INVALID_FORMAT", "message": "The input is invalid." } ] }
// Error - No Body