Kiteworks users API
The users API from Kiteworks — 30 operation(s) for users.
OpenAPI Specification
openapi: 3.0.2
info:
version: '28'
title: Kiteworks API Documentation activities users API
tags:
- name: users
paths:
/rest/users:
delete:
tags:
- users
summary: Deletes Users
description: Mark the specified users as deleted. The size of request User UUID is limited (recommend <= 100)
responses:
'204':
description: Specified users marked as deleted.
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
code: ERR_ACCESS_USER
message: Insufficient access permissions
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_NOT_BOOLEAN, ERR_INPUT_ATTRIBUTE_FORBIDDEN, ERR_INPUT_REQUIRED, ERR_INPUT_NOT_STRING'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_NOT_BOOLEAN:
summary: Input is not a valid boolean
description: Input is not a valid boolean
value:
errors:
code: ERR_INPUT_NOT_BOOLEAN
message: Input is not a valid boolean
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: query
name: id:in
description: List of user IDs to delete.
required: true
schema:
type: string
- in: query
name: retainToUser
description: The ID of the new owner to whom the data will be transferred, applicable when `retainData` and/or `retainPermissionToSharedData` are set to true.
schema:
type: string
- in: query
name: retainToAdvancedFormUser
description: The ID of the user to whom the advanced form data will be transferred, similar to retainToUser but specifically for advanced form components.
schema:
type: string
- in: query
name: remoteWipe
description: Indicates whether to remotely wipe data from both desktop and mobile devices.
schema:
type: boolean
- in: query
name: deleteUnsharedData
description: 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.
schema:
type: boolean
- in: query
name: retainData
description: 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.
schema:
type: boolean
- in: query
name: retainPermissionToSharedData
description: Indicates whether permissions to shared folders should be retained.
schema:
type: boolean
- in: query
name: withdrawFileLinks
description: Indicates whether files sent by deleted or demoted users should be withdrawn.
schema:
type: boolean
- in: query
name: withdrawRequestFiles
description: Indicates whether request files sent by deleted or demoted users should be withdrawn.
schema:
type: boolean
- in: query
name: partialSuccess
description: If set to `true`, the operation will continue for the valid items even if some items result in failure.
schema:
type: boolean
- in: query
name: mode
description: Determines the detail level of the response body.
schema:
type: string
enum:
- full_with_links
- full
/rest/users/actions/login:
post:
tags:
- users
summary: User login
description: Handles user login by accepting the user credentials (username and password).
responses:
'200':
description: Login successful. Returns a redirect URL and success status.
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
examples:
LoginSuccess:
summary: Standard login - no TFA required
value:
success: true
redirectUrl: https://<YOUR_INSTANCE_DOMAIN>/auth/callback
LoginWithTFA:
summary: TFA step required before login is complete
value:
success: false
redirectUrl: https://<YOUR_INSTANCE_DOMAIN>/auth/tfa
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserLogin.Post'
/rest/users/aliveToken:
put:
tags:
- users
summary: Updates token state
description: Updates current session state to be not outdated any more
responses:
'200':
description: Token state updated successfully
'490':
description: Request blocked by WAF
deprecated: false
/rest/users/ldapSearch:
get:
tags:
- users
summary: Find users in LDAP by input supplied
description: Searches the configured LDAP directory for users matching the supplied search criteria.
responses:
'200':
description: Returns users found in LDAP matching the supplied search criteria.
content:
application/json:
schema:
$ref: '#/components/schemas/LdapSearchResults'
examples:
LdapMatches:
summary: LDAP users matching the search
value:
matches:
- email: jane.doe@example.com
displayName: Jane Doe
- email: john.smith@example.com
displayName: John Smith
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: query
name: value
description: The user's email or name
required: true
schema:
type: string
- in: query
name: with
description: With parameters
schema:
type: string
- in: query
name: mode
description: Determines the detail level of the response body.
schema:
type: string
enum:
- full_with_links
- full
- compact
/rest/users/me:
put:
tags:
- users
summary: Update the current user's details
description: Updates the details of the currently authenticated user. For example, change their name or password.
responses:
'200':
description: Currently authenticated user details updated successfully. Returns the updated user object.
content:
application/json:
schema:
$ref: '#/components/schemas/UserMe'
examples:
UpdatedMe:
summary: Current user after update
value:
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':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_PASSWORD_COMPLEXITY_ERROR'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_PASSWORD_COMPLEXITY_ERROR:
summary: Password does not meet complexity requirements
description: Password does not meet complexity requirements
value:
errors:
code: ERR_INPUT_PASSWORD_COMPLEXITY_ERROR
message: Password does not meet complexity requirements
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserNamePassword.Put'
get:
tags:
- users
summary: Retrieve details of the currently logged-in user
description: Fetches the details of the currently authenticated user, including their email address and name.
responses:
'200':
description: Returns the details of the currently authenticated user.
content:
application/json:
schema:
$ref: '#/components/schemas/UserMe'
examples:
CurrentUser:
summary: Authenticated user's details
value:
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
'490':
description: Request blocked by WAF
deprecated: false
/rest/users/me/forcedPasswordChange:
post:
tags:
- users
summary: Change the password for current user after expired
description: Change the password for current user after password expired
responses:
'200':
description: Password changed successfully. Returns a redirect URL for the next step in the authentication flow.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthRedirectResponse'
examples:
PasswordChanged:
summary: Password changed, proceed to next login step
value:
redirectUrl: https://<YOUR_INSTANCE_DOMAIN>/auth/callback
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_PASSWORD_COMPLEXITY_ERROR, ERR_INPUT_REQUIRED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_PASSWORD_COMPLEXITY_ERROR:
summary: Password does not meet complexity requirements
description: Password does not meet complexity requirements
value:
errors:
code: ERR_INPUT_PASSWORD_COMPLEXITY_ERROR
message: Password does not meet complexity requirements
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserForcedPasswordChange.Put'
/rest/users/me/mobileNumber:
put:
tags:
- users
summary: Update mobile number of the current user
description: 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.
responses:
'200':
description: Mobile number updated successfully. Returns the updated user settings.
content:
application/json:
schema:
$ref: '#/components/schemas/Settings'
examples:
MobileNumberUpdated:
summary: Settings after mobile number update
value:
languageId: 1
locationId: 2
signature: ''
storageUsed: 1048576
storageQuota: 10737418240
mobileNumber: '+14155550199'
mobileNumberVerified: false
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED, ERR_INPUT_INVALID_FORMAT'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserMobileNumberPassword.Put'
/rest/users/me/quota:
get:
summary: Retrieve user quota
description: "### Description:\n Retrieves the current user's quota details, including send quota and folder storage quota.\n### Precondition:\n The user profile must have \"Collaboration Allowed\" enabled or have mail access.\n### Response:\n Returns the user's quota information.\n"
tags:
- users
parameters:
- in: query
name: filter
required: false
description: Limit the quota response to a specific quota type.<br>`send` – Returns send quota usage only.<br>`folder` – Returns folder storage quota only.<br>If omitted, both send and folder quota details are returned.
schema:
type: string
responses:
'200':
description: The user quota is successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/UserQuota'
'401':
description: 'Unauthorized<br /><br /><i>Possible error codes: </i>ERR_AUTH_INVALID_CSRF, ERR_AUTH_UNAUTHORIZED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_AUTH_INVALID_CSRF:
summary: Invalid CSRF Authentication
description: Invalid CSRF Authentication
value:
errors:
- code: ERR_AUTH_INVALID_CSRF
message: Invalid CSRF Authentication
ERR_AUTH_UNAUTHORIZED:
summary: Unauthorized
description: Unauthorized
value:
errors:
- code: ERR_AUTH_UNAUTHORIZED
message: Unauthorized
'404':
description: 'Not Found<br /><br /><i>Possible error codes: </i>ERR_ENTITY_NOT_FOUND'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ENTITY_NOT_FOUND:
summary: Entity does not exist
description: Entity does not exist
value:
errors:
- code: ERR_ENTITY_NOT_FOUND
message: Entity does not exist
'490':
description: Request blocked by WAF
/rest/users/me/tfa/auth:
post:
tags:
- users
summary: Two Factor Authentication
description: 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.
responses:
'200':
description: Two Factor Authentication completed. Returns either a redirectUrl string on success or a challengeMsg string if an additional challenge is required.
content:
application/json:
schema:
$ref: '#/components/schemas/TfaChallengeResponse'
examples:
TfaAccepted:
summary: Passcode accepted — login complete
value:
redirectUrl: https://<YOUR_INSTANCE_DOMAIN>/auth/callback
TfaRechallenge:
summary: Additional challenge required
value:
challengeMsg: Incorrect passcode. Please try again.
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserTfa.Post'
/rest/users/me/tfa/challenge:
post:
tags:
- users
summary: Two Factor Authentication
description: 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.
responses:
'200':
description: Two Factor Authentication challenge initiated successfully. Returns either a challengeMsg string or a redirectUrl string depending on the authentication flow.
content:
application/json:
schema:
$ref: '#/components/schemas/TfaChallengeResponse'
examples:
ChallengeInitiated:
summary: Passcode delivered — waiting for user input
value:
challengeMsg: A passcode has been sent to your mobile device.
ChallengeAccepted:
summary: Module accepted immediately — login complete
value:
redirectUrl: https://<YOUR_INSTANCE_DOMAIN>/auth/callback
'490':
description: Request blocked by WAF
deprecated: false
parameters:
- in: query
name: referral
description: Referral URL
schema:
type: string
/rest/users/me/tfa/config:
get:
tags:
- users
summary: Two Factor Authentication
description: 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:
'200':
description: Two Factor Authentication configuration retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/TfaConfigResponse'
examples:
TfaConfigSms:
summary: SMSOTP module with configurable mobile number
value:
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
TfaConfigTotp:
summary: TOTP module (no SMSOTP-specific fields)
value:
module: TOTP
passcodeLabel: Authenticator code
passcodeDescription: Enter the 6-digit code from your authenticator app.
rechallengeLabel: ''
challengeShouldSendPassword: false
challengeWaitMessage: ''
rechallengeMessage: ''
rememberDeviceEnabled: true
passcodeMask: false
'490':
description: Request blocked by WAF
deprecated: false
/rest/users/me/tfa/resetTotpSecret:
post:
tags:
- users
summary: Reset secret key for time-based OTP of the current user
description: 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.
responses:
'200':
description: Returns TOTP setup details when initiating the reset, or a verification result when confirming with an OTP.
content:
application/json:
schema:
$ref: '#/components/schemas/TotpSetupResponse'
examples:
TotpSetupInitiated:
summary: New TOTP secret generated for setup
value:
username: alice@example.com
issuer: kiteworks
secret: JBSWY3DPEHPK3PXP
image: data:image/png;base64,iVBOR...
TotpSetupVerified:
summary: TOTP secret verified successfully
value:
code: 1
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_PASSWORD_COMPLEXITY_ERROR, ERR_INPUT_REQUIRED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_PASSWORD_COMPLEXITY_ERROR:
summary: Password does not meet complexity requirements
description: Password does not meet complexity requirements
value:
errors:
code: ERR_INPUT_PASSWORD_COMPLEXITY_ERROR
message: Password does not meet complexity requirements
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserTfaTotpResetSecret.Post'
/rest/users/me/tfa/setupTotpSecret:
get:
tags:
- users
summary: Setup secret key for Time-based OTP of the current user
description: 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:
'200':
description: TOTP secret setup initiated successfully. Returns the username, issuer, secret key, QR code image, and optional setup instructions.
content:
application/json:
schema:
$ref: '#/components/schemas/TotpSetupResponse'
examples:
TotpSetup:
summary: New TOTP secret ready to scan
value:
username: jane.doe@example.com
issuer: Kiteworks
secret: JBSWY3DPEHPK3PXP
image: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...
'490':
description: Request blocked by WAF
deprecated: false
/rest/users/me/tfa/verifyTotpSecret:
post:
tags:
- users
summary: Verify code for finalising secret key for Time-based OTP
description: 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.
responses:
'200':
description: TOTP secret verified successfully. Returns a redirectUrl string for the next step in the authentication flow.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthRedirectResponse'
examples:
TotpVerified:
summary: TOTP secret confirmed — proceed to next login step
value:
redirectUrl: https://<YOUR_INSTANCE_DOMAIN>/auth/callback
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserTfaTotpVerifySecret.Post'
/rest/users/me/tfaSetup:
put:
tags:
- users
summary: Setup 2FA settings
description: 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.
responses:
'200':
description: 2FA settings updated successfully. Returns a redirect URL for the next step in the authentication flow.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthRedirectResponse'
examples:
TfaSetup:
summary: Redirect URL after 2FA setup
value:
redirectUrl: /rest/auth/login
'403':
description: 'Forbidden<br /><br /><i>Possible error codes: </i>ERR_ACCESS_USER'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_ACCESS_USER:
summary: Insufficient access permissions
description: Insufficient access permissions
value:
errors:
code: ERR_ACCESS_USER
message: Insufficient access permissions
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserTfa.Put'
/rest/users/me/tos:
get:
tags:
- users
summary: Terms of Service
description: 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:
'200':
description: Terms of Service retrieved successfully. Returns the TOS type, content, acceptance text, occurrence, and whether acceptance is required.
content:
application/json:
schema:
$ref: '#/components/schemas/TosResponse'
examples:
TosData:
summary: TOS requiring acceptance on every login
value:
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
'490':
description: Request blocked by WAF
deprecated: false
post:
tags:
- users
summary: Terms of Service
description: 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.
responses:
'200':
description: 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.
content:
application/json:
schema:
$ref: '#/components/schemas/AuthRedirectResponse'
examples:
TosAccepted:
summary: TOS accepted — proceed to next login step
value:
redirectUrl: https://<YOUR_INSTANCE_DOMAIN>/auth/callback
'422':
description: 'Unprocessable Content<br /><br /><i>Possible error codes: </i>ERR_INPUT_REQUIRED'
content:
application/json:
schema:
$ref: '#/components/schemas/Errors'
examples:
ERR_INPUT_REQUIRED:
summary: Field is required
description: Field is required
value:
errors:
code: ERR_INPUT_REQUIRED
message: Field is required
'490':
description: Request blocked by WAF
deprecated: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserTos.Post'
/rest/users/preauth:
post:
tags:
- users
summary: User login preauth
description: User login preauth.
responses:
'200':
description: 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.
content:
# --- truncated at 32 KB (112 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kiteworks/refs/heads/main/openapi/kiteworks-users-api-openapi.yml