{
"openapi": "3.0.2",
"info": {
"version": "28",
"title": "Kiteworks API — adminRoles Operations"
},
"paths": {
"/rest/adminRoles": {
"get": {
"tags": [
"adminRoles"
],
"summary": "List admin roles",
"description": "Returns a list of admin roles available in Kiteworks (e.g. System Admin, Application Admin).",
"responses": {
"200": {
"description": "Returns a list of admin role records.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AdminRole"
}
}
}
},
"examples": {
"Admin role list": {
"summary": "All available admin roles",
"value": [
{
"id": 1,
"name": "System Admin",
"guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
{
"id": 2,
"name": "Application Admin",
"guid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
]
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "query",
"name": "orderBy",
"description": "Sorting options",
"schema": {
"type": "array",
"items": {
"type": "string"
},
"enum": [
"id:asc",
"id:desc",
"name:asc",
"name:desc"
]
}
},
{
"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"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/adminRoles\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nurl = \"https://{instance}.kiteworks.com/rest/adminRoles\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/adminRoles/{id}": {
"get": {
"tags": [
"adminRoles"
],
"summary": "Get an admin role",
"description": "Returns the details of the specified admin role.",
"responses": {
"200": {
"description": "Returns the admin role record.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminRole"
},
"examples": {
"Admin role": {
"summary": "A single admin role record",
"value": {
"id": 2,
"name": "Application Admin",
"guid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
}
}
}
}
},
"490": {
"description": "Request blocked by WAF"
}
},
"deprecated": false,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the admin role.",
"required": true,
"schema": {
"type": "integer"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/adminRoles/:id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the admin role.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/adminRoles/{id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/adminRoles/{id}/users": {
"get": {
"tags": [
"adminRoles"
],
"summary": "List users with an admin role",
"description": "Returns the list of users who have been assigned the specified admin role.",
"responses": {
"200": {
"description": "Returns a list of user records assigned to the specified admin role.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"Users with admin role": {
"summary": "Users assigned to Application Admin",
"value": {
"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
}
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: 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,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the admin role.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "email",
"description": "Filter users based on their email address.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "email:contains",
"description": "Filter users based on their email address.. Search for results that contain the specified characters in this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "name",
"description": "Filter users based on their full name.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "name:contains",
"description": "Filter users based on their full name.. Search for results that contain the specified characters in this parameter.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "metadata",
"description": "Filter users based on their metadata information.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "metadataContains",
"description": "Filter users whose metadata contains the specified characters.",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "deleted",
"description": "Filter users based on whether they have been deleted.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "active",
"description": "Filter users based on whether they are active in the system.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "verified",
"description": "Filter users based on their verification status.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "suspended",
"description": "Filter users based on whether they are suspended.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "isRecipient",
"description": "Filter users who are recipients of specific items.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "allowsCollaboration",
"description": "Filter users whose profiles allow collaboration access.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "created",
"description": "Filter users based on the creation date of their account.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "created:gt",
"description": "Filter users based on the creation date of their account.. Search for results where this parameter value is greater than the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "created:gte",
"description": "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.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "created:lt",
"description": "Filter users based on the creation date of their account.. Search for results where this parameter value is less than the specified value.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "created:lte",
"description": "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.",
"schema": {
"type": "string",
"format": "date"
}
},
{
"in": "query",
"name": "orderBy",
"description": "Sorting options",
"schema": {
"type": "array",
"items": {
"type": "string"
},
"enum": [
"id:asc",
"id:desc",
"created:asc",
"created:desc",
"email:asc",
"email:desc",
"name:asc",
"name:desc"
]
}
},
{
"in": "query",
"name": "offset",
"description": "Offset",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "limit",
"description": "Limit",
"schema": {
"type": "integer"
}
},
{
"in": "query",
"name": "locate_id",
"description": "If specified, \"offset\" parameter will be ignored\n and the page containing entity with this Id will be returned.",
"schema": {
"type": "integer"
}
},
{
"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"
]
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X GET \\\n \"https://{instance}.kiteworks.com/rest/adminRoles/:id/users\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the admin role.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/adminRoles/{id}/users\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.get(url, headers=headers)\nprint(response.json())"
}
]
}
},
"/rest/adminRoles/{id}/users/{user_id}": {
"put": {
"tags": [
"adminRoles"
],
"summary": "Assign an admin role to a user",
"description": "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`.",
"responses": {
"200": {
"description": "Returns the newly created admin role assignment.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserAdminRole"
}
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
}
}
},
"examples": {
"Role assigned": {
"summary": "User assigned to Application Admin",
"value": [
{
"user_id": 10,
"admin_role": 2
}
]
}
}
}
}
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_SYSTEM_ADMIN, ERR_LICENSE_DLI, ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_SYSTEM_ADMIN": {
"summary": "Authenticated user is not a System Admin",
"description": "Authenticated user is not a System Admin",
"value": {
"errors": {
"code": "ERR_ACCESS_SYSTEM_ADMIN",
"message": "Authenticated user is not a System Admin"
}
}
},
"ERR_LICENSE_DLI": {
"summary": "Feature DLI is not enabled by license",
"description": "Feature DLI is not enabled by license",
"value": {
"errors": {
"code": "ERR_LICENSE_DLI",
"message": "Feature DLI is not enabled by license"
}
}
},
"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,
"parameters": [
{
"in": "path",
"name": "id",
"description": "ID of the Admin role",
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "path",
"name": "user_id",
"description": "ID of user to promote admin role",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "deleteAdvancedFormData",
"description": "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.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "retainToAdvancedFormUser",
"description": "User ID to retain advanced form data to when deleteAdvancedFormData is false. Required when deleteAdvancedFormData is false.",
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X PUT \\\n \"https://{instance}.kiteworks.com/rest/adminRoles/:id/users/:user_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # ID of the Admin role\nuser_id = \"VALUE\" # ID of user to promote admin role\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/adminRoles/{id}/users/{user_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.put(url, headers=headers)\nprint(response.json())"
}
]
},
"delete": {
"tags": [
"adminRoles"
],
"summary": "Remove an admin role from a user",
"description": "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`.",
"responses": {
"204": {
"description": "The admin role was successfully removed from the user. Returns no content."
},
"403": {
"description": "Forbidden
Possible error codes: ERR_ACCESS_SYSTEM_ADMIN, ERR_ACCESS_USER",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Errors"
},
"examples": {
"ERR_ACCESS_SYSTEM_ADMIN": {
"summary": "Authenticated user is not a System Admin",
"description": "Authenticated user is not a System Admin",
"value": {
"errors": {
"code": "ERR_ACCESS_SYSTEM_ADMIN",
"message": "Authenticated user is not a System Admin"
}
}
},
"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,
"parameters": [
{
"in": "path",
"name": "id",
"description": "The unique identifier of the admin role to remove from the user.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"in": "path",
"name": "user_id",
"description": "The unique identifier (UUID) of the user.",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "deleteAdvancedFormData",
"description": "Whether to delete advanced form data when removing role with advanced form access. Required when role has advanced form access.",
"schema": {
"type": "boolean"
}
},
{
"in": "query",
"name": "retainToAdvancedFormUser",
"description": "User ID to retain advanced form data to when deleteAdvancedFormData is false. Required when deleteAdvancedFormData is false.",
"schema": {
"type": "string"
}
}
],
"x-codeSamples": [
{
"lang": "Shell",
"label": "cURL",
"source": "curl -X DELETE \\\n \"https://{instance}.kiteworks.com/rest/adminRoles/:id/users/:user_id\" \\\n -H \"Authorization: Bearer YOUR_TOKEN\""
},
{
"lang": "Python",
"label": "Python",
"source": "import requests\n\nid = \"VALUE\" # The unique identifier of the admin role to remove from the user.\nuser_id = \"VALUE\" # The unique identifier (UUID) of the user.\n\nurl = f\"https://{{instance}}.kiteworks.com/rest/adminRoles/{id}/users/{user_id}\"\nheaders = {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n}\nresponse = requests.delete(url, headers=headers)\nprint(response.json())"
}
]
}
}
},
"components": {
"schemas": {
"AdminRole": {
"description": "Class AdminRole",
"required": [
"id",
"name"
],
"properties": {
"id": {
"description": "Admin role unique identifier",
"type": "integer"
},
"name": {
"description": "Display name of the admin role",
"type": "string"
},
"guid": {
"description": "Admin role globally unique identifier",
"type": "string"
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"User": {
"description": "Class User",
"required": [
"basedirId",
"email",
"id",
"mydirId",
"name",
"syncdirId"
],
"properties": {
"id": {
"description": "The unique identifier of the user",
"type": "string"
},
"basedirId": {
"description": "The unique identifier of the user's root Kiteworks directory.",
"type": "string"
},
"created": {
"description": "Date and time the user account was created",
"type": "string",
"format": "date"
},
"email": {
"description": "The user's email",
"type": "string"
},
"mydirId": {
"description": "The unique identifier of the user's mydir system directory.",
"type": "string"
},
"name": {
"description": "The name of the user",
"type": "string"
},
"syncdirId": {
"description": "The unique identifier of the user's 'My Folder'.",
"type": "string"
},
"userTypeId": {
"description": "The unique identifier of the user type (profile).",
"type": "integer"
},
"internal": {
"description": "Indicates whether the user is an internal user",
"type": "boolean"
},
"profileIcon": {
"description": "URL to the user's profile icon image",
"type": "string"
},
"extDL": {
"description": "Indicates whether the user is an External Distribution List",
"type": "boolean"
},
"metadata": {
"description": "List of user's metadata",
"type": "array",
"items": {
"$ref": "#/components/schemas/UserMetadata"
}
},
"adminRoleId": {
"description": "The ID of the admin role assigned to the user.",
"type": "integer"
},
"links": {
"description": "HATEOAS links associated with the entity",
"type": "array",
"items": {
"type": "string"
}
},
"active": {
"description": "Indicates whether the user is an actual kitework user",
"type": "boolean"
},
"suspended": {
"description": "Indicates whether the user is suspended",
"type": "boolean"
},
"deleted": {
"description": "Indicates whether the user has been deleted",
"type": "boolean"
},
"flags": {
"description": "Authentication type.\n * 0: No authentication,\n * 1: Authentication by kiteworks,\n * 2: Authentication by LDAP,\n * 4: Authentication by SSO",
"type": "integer"
},
"verified": {
"description": "Indicates whether the user is verified",
"type": "boolean"
},
"deactivated": {
"description": "Indicates whether the user has been deactivated",
"type": "boolean"
},
"lastActivityDateTime": {
"description": "User's last activity datetime",
"type": "string",
"format": "date"
},
"passwordExpirationDateTime": {
"description": "The exact timestamp when the user's password will expire",
"type": "string",
"format": "date"
}
}
},
"MetaData": {
"type": "object",
"properties": {
"total": {
"type": "integer",
"description": "Total number of items available."
},
"limit": {
"type": "integer",
"description": "Maximum number of items returned per page."
},
"offset": {
"type": "integer",
"description": "Number of items skipped before the current page."
}
}
},
"Errors": {
"type": "object",
"properties": {
"error": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"UserAdminRole": {
"description": "Class UserAdminRole",
"required": [
"userId"
],
"properties": {
"userId": {
"description": "User unique identifier",
"type": "string"
},
"adminRole": {
"description": "Admin role unique identifier. Possible values are: 1: System admin, 2: Application admin",
"type": "string"
}
}
},
"Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
},
"UserMetadata": {
"description": "Class UserMetadata",
"properties": {
"name": {
"description": "Key name of the custom metadata attribute associated with the user",
"type": "string"
},
"value": {
"description": "Value assigned to the custom metadata attribute for the user",
"type": "string"
}
}
}
}
}
}