adminRoles

5 endpoints
GET/rest/adminRoles

List admin roles

Returns a list of admin roles available in Kiteworks (e.g. System Admin, Application Admin).

Parameters
Query Parameters
orderBy
Optional
string[]

Sorting options

with
Optional
string

With parameters

mode
Optional
string

Determines the detail level of the response body.

Responses

Returns a list of admin role records.

id
Required
integer

Admin role unique identifier

name
Required
string

Display name of the admin role

guid
string

Admin role globally unique identifier

links
string[]

HATEOAS links associated with the entity

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/adminRoles" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

url = "https://{instance}.kiteworks.com/rest/adminRoles"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
[ { "id": 1, "name": "System Admin", "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, { "id": 2, "name": "Application Admin", "guid": "b2c3d4e5-f6a7-8901-bcde-f12345678901" } ]
// Error - No Body
GET/rest/adminRoles/{id}

Get an admin role

Returns the details of the specified admin role.

Parameters
Path Parameters
id
Required
integer

The unique identifier of the admin role.

Responses

Returns the admin role record.

id
Required
integer

Admin role unique identifier

name
Required
string

Display name of the admin role

guid
string

Admin role globally unique identifier

links
string[]

HATEOAS links associated with the entity

Request blocked by WAF

Empty response body.
Shell
curl -X GET \
  "https://{instance}.kiteworks.com/rest/adminRoles/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # The unique identifier of the admin role.

url = f"https://{{instance}}.kiteworks.com/rest/adminRoles/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "id": 2, "name": "Application Admin", "guid": "b2c3d4e5-f6a7-8901-bcde-f12345678901" }
// Error - No Body
GET/rest/adminRoles/{id}/users

List users with an admin role

Returns the list of users who have been assigned the specified admin role.

Parameters
Path Parameters
id
Required
integer

The unique identifier of the admin role.

Query Parameters
email
Optional
string

Filter users based on their email address.

email:contains
Optional
string

Filter users based on their email address.. Search for results that contain the specified characters in this parameter.

name
Optional
string

Filter users based on their full name.

name:contains
Optional
string

Filter users based on their full name.. Search for results that contain the specified characters in this parameter.

metadata
Optional
string

Filter users based on their metadata information.

metadataContains
Optional
string

Filter users whose metadata contains the specified characters.

deleted
Optional
boolean

Filter users based on whether they have been deleted.

active
Optional
boolean

Filter users based on whether they are active in the system.

verified
Optional
boolean

Filter users based on their verification status.

suspended
Optional
boolean

Filter users based on whether they are suspended.

isRecipient
Optional
boolean

Filter users who are recipients of specific items.

allowsCollaboration
Optional
boolean

Filter users whose profiles allow collaboration access.

created
Optional
string

Filter users based on the creation date of their account.

created:gt
Optional
string

Filter users based on the creation date of their account.. Search for results where this parameter value is greater than the specified value.

created:gte
Optional
string

Filter users based on the creation date of their account.. Search for results where this parameter value is greater than or equal to the specified value.

created:lt
Optional
string

Filter users based on the creation date of their account.. Search for results where this parameter value is less than the specified value.

created:lte
Optional
string

Filter users based on the creation date of their account.. Search for results where this parameter value is less than or equal to the specified value.

orderBy
Optional
string[]

Sorting options

offset
Optional
integer

Offset

limit
Optional
integer

Limit

locate_id
Optional
integer

If specified, "offset" parameter will be ignored
and the page containing entity with this Id will be returned.

with
Optional
string

With parameters

mode
Optional
string

Determines the detail level of the response body.

Responses

Returns a list of user records assigned to the specified admin role.

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

active
boolean

Indicates whether the user is an actual kitework user

suspended
boolean

Indicates whether the user is suspended

deleted
boolean

Indicates whether the user has been deleted

flags
integer

Authentication type.

  • 0: No authentication,
  • 1: Authentication by kiteworks,
  • 2: Authentication by LDAP,
  • 4: Authentication by SSO

verified
boolean

Indicates whether the user is verified

deactivated
boolean

Indicates whether the user has been deactivated

lastActivityDateTime
string

User's last activity datetime

passwordExpirationDateTime
string

The exact timestamp when the user's password will expire

total
integer

Total number of items available.

limit
integer

Maximum number of items returned per page.

offset
integer

Number of items skipped before the current page.

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/adminRoles/:id/users" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # The unique identifier of the admin role.

url = f"https://{{instance}}.kiteworks.com/rest/adminRoles/{id}/users"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.get(url, headers=headers)
print(response.json())
Responses
{ "data": [ { "id": 10, "name": "Alice Johnson", "email": "alice@example.com", "username": "alice.johnson" }, { "id": 11, "name": "Bob Smith", "email": "bob@example.com", "username": "bob.smith" } ], "total": 2, "page": 1, "pageSize": 20 }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
PUT/rest/adminRoles/{id}/users/{user_id}

Assign an admin role to a user

Assigns the specified admin role to a user, replacing any previously assigned role. If the user's current role has advanced form access and the new role does not, you must specify how to handle the advanced form data via deleteAdvancedFormData and optionally retainToAdvancedFormUser.

Parameters
Path Parameters
id
Required
integer

ID of the Admin role

user_id
Required
string

ID of user to promote admin role

Query Parameters
deleteAdvancedFormData
Optional
boolean

Whether to delete advanced form data when changing to role without advanced form access. Required when current role has advanced form access and new role does not.

retainToAdvancedFormUser
Optional
string

User ID to retain advanced form data to when deleteAdvancedFormData is false. Required when deleteAdvancedFormData is false.

Responses

Returns the newly created admin role assignment.

userId
Required
string

User unique identifier

adminRole
string

Admin role unique identifier. Possible values are: 1: System admin, 2: Application admin

total
integer

Total number of items available.

limit
integer

Maximum number of items returned per page.

offset
integer

Number of items skipped before the current page.

Forbidden

Possible error codes: ERR_ACCESS_SYSTEM_ADMIN, ERR_LICENSE_DLI, 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/adminRoles/:id/users/:user_id" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # ID of the Admin role
user_id = "VALUE"  # ID of user to promote admin role

url = f"https://{{instance}}.kiteworks.com/rest/adminRoles/{id}/users/{user_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.put(url, headers=headers)
print(response.json())
Responses
[ { "user_id": 10, "admin_role": 2 } ]
{ "errors": { "code": "ERR_ACCESS_SYSTEM_ADMIN", "message": "Authenticated user is not a System Admin" } }
{ "errors": { "code": "ERR_LICENSE_DLI", "message": "Feature DLI is not enabled by license" } }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
DELETE/rest/adminRoles/{id}/users/{user_id}

Remove an admin role from a user

Removes the specified admin role from a user. The user account itself is not deleted. If the role being removed has advanced form access, you must specify how to handle the advanced form data via deleteAdvancedFormData and optionally retainToAdvancedFormUser.

Parameters
Path Parameters
id
Required
integer

The unique identifier of the admin role to remove from the user.

user_id
Required
string

The unique identifier (UUID) of the user.

Query Parameters
deleteAdvancedFormData
Optional
boolean

Whether to delete advanced form data when removing role with advanced form access. Required when role has advanced form access.

retainToAdvancedFormUser
Optional
string

User ID to retain advanced form data to when deleteAdvancedFormData is false. Required when deleteAdvancedFormData is false.

Responses

The admin role was successfully removed from the user. Returns no content.

Empty response body.

Forbidden

Possible error codes: ERR_ACCESS_SYSTEM_ADMIN, 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/adminRoles/:id/users/:user_id" \
  -H "Authorization: Bearer YOUR_TOKEN"
Python
import requests

id = "VALUE"  # The unique identifier of the admin role to remove from the user.
user_id = "VALUE"  # The unique identifier (UUID) of the user.

url = f"https://{{instance}}.kiteworks.com/rest/adminRoles/{id}/users/{user_id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}
response = requests.delete(url, headers=headers)
print(response.json())
Responses
// Request successful - No Body
{ "errors": { "code": "ERR_ACCESS_SYSTEM_ADMIN", "message": "Authenticated user is not a System Admin" } }
{ "errors": { "code": "ERR_ACCESS_USER", "message": "Insufficient access permissions" } }
// Error - No Body
Previousadmin
Nextcards