# Kiteworks API — ldapGroups Operations

**5 endpoints** | [Browse interactive reference](https://developer.kiteworks.com/api-reference/ldapGroups.html) | [Download spec slice](https://developer.kiteworks.com/assets/specs/ldapGroups.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/ldapGroups

**Summary:** Returns a list of LDAP groups.

Returns a list of LDAP groups that have been enabled through the kiteworks admin.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `name` | query | no | LDAP group name |
| `name:contains` | query | no | LDAP group name. Search for results that contain the specified characters in this parameter. |
| `email` | query | no | LDAP group email. |
| `email:contains` | query | no | LDAP group email.. Search for results that contain the specified characters in this parameter. |
| `orderBy` | query | no | Sorting options |
| `offset` | query | no | Offset |
| `limit` | query | no | Limit |
| `with` | query | no | With parameters |
| `mode` | query | no | Determines the detail level of the response body. |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | List of LDAP groups retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (LdapGroupList):**

```json
{
  "data": [
    {
      "id": 1,
      "name": "Engineering",
      "email": "engineering@example.com",
      "description": "Engineering team LDAP group"
    }
  ],
  "metadata": {
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

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

---

## POST /rest/ldapGroups

**Summary:** Create an LDAP group

Creates a new LDAP group by looking up the provided distinguished name (DN) in the directory. Returns 422 if the DN is invalid or not found.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `returnEntity` | query | no | If set to `true`, returns information about the newly created entity. |
| `mode` | query | no | Determines the detail level of the response body. |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `dn` | string | yes | LDAP distinguished name (DN) |
| `email` | string | no | LDAP group email address |
| `description` | string | no | LDAP group description |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | LDAP group created successfully. |
| 422 | Unprocessable Content  <i>Possible error codes: </i>ERR_INPUT_REQUIRED, ERR_INPUT_INVALID_EMAIL |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (LdapGroupCreated):**

```json
{
  "id": 5,
  "name": "Engineering",
  "email": "engineering@example.com",
  "description": "Engineering team LDAP group"
}
```

**422 (ERR_INPUT_REQUIRED):**

```json
{
  "errors": {
    "code": "ERR_INPUT_REQUIRED",
    "message": "Field is required"
  }
}
```

**422 (ERR_INPUT_INVALID_EMAIL):**

```json
{
  "errors": {
    "code": "ERR_INPUT_INVALID_EMAIL",
    "message": "Input is not a valid email"
  }
}
```

**Code Samples:**

**cURL:**

```shell
curl -X POST \
  "https://{instance}.kiteworks.com/rest/ldapGroups" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "dn": "string",
         "email": "string",
         "description": "string",
         "addLinks": true
       }'
```

**Python:**

```python
import requests

url = "https://{instance}.kiteworks.com/rest/ldapGroups"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "dn": "string",
  "email": "string",
  "description": "string",
  "addLinks": true
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

---

## GET /rest/ldapGroups/{id}

**Summary:** Gets an LDAP group

Returns the details of the specified LDAP group, including its name, email address, and description.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the LDAP group to be retrieved |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | LDAP group details retrieved successfully. |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (LdapGroupInfo):**

```json
{
  "id": 1,
  "name": "Engineering",
  "email": "engineering@example.com",
  "description": "Engineering team LDAP group"
}
```

**Code Samples:**

**cURL:**

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

**Python:**

```python
import requests

id = "VALUE"  # ID of the LDAP group to be retrieved

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

---

## PUT /rest/ldapGroups/{id}

**Summary:** Updates an LDAP group

Updates the settings of the specified LDAP group.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the LDAP to update |

**Request Body:**

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `email` | string | no | LDAP group email address |
| `description` | string | no | LDAP group description |
| `addLinks` | boolean | no | Indicates whether HATEOAS links should be included in the response |

**Responses:**

| Code | Description |
|------|-------------|
| 200 | LDAP group updated successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**200 (LdapGroupUpdated):**

```json
{
  "id": 1,
  "name": "Engineering",
  "email": "eng-updated@example.com",
  "description": "Updated engineering team LDAP group"
}
```

**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/ldapGroups/:id" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
         "email": "string",
         "description": "string",
         "addLinks": true
       }'
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the LDAP to update

url = f"https://{{instance}}.kiteworks.com/rest/ldapGroups/{id}"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
}
payload = {
  "email": "string",
  "description": "string",
  "addLinks": true
}
response = requests.put(url, headers=headers, json=payload)
print(response.json())
```

---

## DELETE /rest/ldapGroups/{id}

**Summary:** Deletes an LDAP group

Permanently deletes the specified LDAP group.

**Parameters:**

| Name | In | Required | Description |
|------|----|----------|-------------|
| `id` | path | yes | ID of the LDAP group to delete |

**Responses:**

| Code | Description |
|------|-------------|
| 204 | LDAP group deleted successfully. |
| 403 | Forbidden  <i>Possible error codes: </i>ERR_ACCESS_USER |
| 490 | Request blocked by WAF |

**Response Examples:**

**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/ldapGroups/:id" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Python:**

```python
import requests

id = "VALUE"  # ID of the LDAP group to delete

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

---