# Kiteworks API — adminRoles Operations

**5 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/adminRoles.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/adminRoles.json)

> **Authentication required.** All requests must include a Bearer access token in the
> `Authorization` header. See [Authentication](https://developer.kiteworks.com/authentication.md) for how to
> obtain a token using OAuth 2.0 Authorization Code (PKCE) or JWT Bearer flow.

---

## GET /rest/adminRoles

**Summary:** List admin roles

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

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `orderBy` | query | no | Sorting options |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a list of admin role records. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Admin role list):**

```json
[
  {
    "id": 1,
    "name": "System Admin",
    "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  {
    "id": 2,
    "name": "Application Admin",
    "guid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }
]
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## GET /rest/adminRoles/{id}

**Summary:** Get an admin role

Returns the details of the specified admin role.

**Parameters:**

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

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the admin role record. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Admin role):**

```json
{
  "id": 2,
  "name": "Application Admin",
  "guid": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```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())
```

---

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

**Summary:** List users with an admin role

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

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the admin role. |
| `email` | query | no | Filter users based on their email address. |
| `email:contains` | query | no | Filter users based on their email address.. Search for results that contain the specified characters in this parameter. |
| `name` | query | no | Filter users based on their full name. |
| `name:contains` | query | no | Filter users based on their full name.. Search for results that contain the specified characters in this parameter. |
| `metadata` | query | no | Filter users based on their metadata information. |
| `metadataContains` | query | no | Filter users whose metadata contains the specified characters. |
| `deleted` | query | no | Filter users based on whether they have been deleted. |
| `active` | query | no | Filter users based on whether they are active in the system. |
| `verified` | query | no | Filter users based on their verification status. |
| `suspended` | query | no | Filter users based on whether they are suspended. |
| `isRecipient` | query | no | Filter users who are recipients of specific items. |
| `allowsCollaboration` | query | no | Filter users whose profiles allow collaboration access. |
| `created` | query | no | Filter users based on the creation date of their account. |
| `created:gt` | query | no | 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` | query | no | 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` | query | no | 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` | query | no | 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` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `locate_id` | query | no | If specified, "offset" parameter will be ignored                                             and the page containing entity with this Id will be returned. |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns a list of user records assigned to the specified admin role. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Users with admin role):**

```json
{
  "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 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

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

**Python:**

```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())
```

---

## PUT /rest/adminRoles/{id}/users/{user_id}

**Summary:** 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:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the Admin role |
| `user_id` | path | yes | ID of user to promote admin role |
| `deleteAdvancedFormData` | query | no | 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` | query | no | User ID to retain advanced form data to when deleteAdvancedFormData is false. Required when deleteAdvancedFormData is false. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | Returns the newly created admin role assignment. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_SYSTEM_ADMIN, ERR_LICENSE_DLI, ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (Role assigned):**

```json
[
  {
    "user_id": 10,
    "admin_role": 2
  }
]
```

**403 (ERR_ACCESS_SYSTEM_ADMIN):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_SYSTEM_ADMIN",
    "message": "Authenticated user is not a System Admin"
  }
}
```

**403 (ERR_LICENSE_DLI):**

```json
{
  "errors": {
    "code": "ERR_LICENSE_DLI",
    "message": "Feature DLI is not enabled by license"
  }
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

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

**Python:**

```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())
```

---

## DELETE /rest/adminRoles/{id}/users/{user_id}

**Summary:** 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:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | The unique identifier of the admin role to remove from the user. |
| `user_id` | path | yes | The unique identifier (UUID) of the user. |
| `deleteAdvancedFormData` | query | no | Whether to delete advanced form data when removing role with advanced form access. Required when role has advanced form access. |
| `retainToAdvancedFormUser` | query | no | User ID to retain advanced form data to when deleteAdvancedFormData is false. Required when deleteAdvancedFormData is false. |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | The admin role was successfully removed from the user. Returns no content. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_SYSTEM_ADMIN, ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**403 (ERR_ACCESS_SYSTEM_ADMIN):**

```json
{
  "errors": {
    "code": "ERR_ACCESS_SYSTEM_ADMIN",
    "message": "Authenticated user is not a System Admin"
  }
}
```

**403 (ERR_ACCESS_USER):**

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

**Code Samples:**

**cURL:**

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

**Python:**

```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())
```

---