---
type: api
title: Update a conversation's access control
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-put-agent-builder-conversations-conversation-id-access-control
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-put-agent-builder-conversations-conversation-id-access-control
products:
  - Kibana
---

# Update a conversation's access control

Availability: Planned

- Server: `https://{kibana_url}`

## Paths

- `PUT` `/api/agent_builder/conversations/{conversation_id}/access_control`
- `PUT` `/s/{space_id}/api/agent_builder/conversations/{conversation_id}/access_control`

- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#apikeyauth)
- [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#basicauth)

#### Path Parameters

- `conversation_id` (string · max: 256)
  The unique identifier of the conversation whose access control to update.

## Description

Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.

Replace a conversation's access mode and member list. Only the conversation owner can call this endpoint; every other caller receives a not-found response. Each call replaces the entire access control — the most recent successful update wins. Members can read and continue the conversation, but still need access to the conversation's agent. To learn more about agent conversations, refer to the [agent chat documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/chat).<br/><br/>[Required authorization] Route required privileges: agentBuilder:read.

## Request Body

`application/json`

- `access_mode` (enum) — required
  Access-control mode: `private` (only the owner and the listed members can read and continue the conversation), `public` (any user with access to the conversation's agent can read and continue it).
  Values: `private`, `public`
- `entries` ([] object · max: 100) — required
  Members to share the conversation with. The list replaces the stored one; submit an empty list to unshare. Entries naming the owner are ignored. Must be empty when `access_mode` is `public`; repeated ids are rejected.
  - `id` (string · min: 1 · max: 1024) — required
    Stable identifier of the user to share the conversation with: a Kibana user profile uid. Users without a profile cannot be granted access.
  - `role` (enum) — required
    Role granted to the principal. `member` is the only role: it grants read and converse access to the conversation.
    Values: `member`
  - `type` (enum) — required
    Values: `user`

## Responses

#### `200`

Indicates a successful response

#### `400`

Bad Request — the request body failed validation.

#### `404`

Not Found — no conversation with this ID is readable by the caller, or the caller is not its owner. Matches the existing `conversationNotFound` shape, so members cannot distinguish a conversation they may not re-share from one that does not exist.

## Code Examples

#### Console

```console
PUT kbn://api/agent_builder/conversations/{conversation_id}/access_control
{
  "access_mode": "private",
  "entries": [
    { "type": "user", "id": "u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0", "role": "member" }
  ]
}
```

#### curl

```curl
curl \
  -X PUT "${KIBANA_URL}/api/agent_builder/conversations/{conversation_id}/access_control" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "access_mode": "private",
    "entries": [
      { "type": "user", "id": "u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0", "role": "member" }
    ]
  }'
```

## Response Examples

#### Update conversation access control response

Example response returning the persisted access control. `added_at` is stamped by the server for newly added members and preserved for members that were already listed.

```json
{
  "access_mode": "private",
  "entries": [
    {
      "added_at": "2026-08-11T10:00:00.000Z",
      "id": "u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0",
      "role": "member",
      "type": "user"
    },
    {
      "added_at": "2026-08-11T11:30:00.000Z",
      "id": "u_9xXGnqPB4mLTNhOlHMHXqYbGrGFOTuQIRWlqLpKq0dE_0",
      "role": "member",
      "type": "user"
    }
  ]
}
```

#### Duplicate entry response

Two entries name the same user id.

```json
{
  "error": "Bad Request",
  "message": "Duplicate ACL entry for user \u0022u_kd2Wm6QCf9nBBqGGyfxBcQxIrgLLLLxbPHOTNHOTgWM_0\u0022",
  "statusCode": 400
}
```

#### Entries with public mode response

`entries` must be empty when `access_mode` is `public` — a public conversation is already open to everyone with agent access.

```json
{
  "error": "Bad Request",
  "message": "ACL entries are not supported when access_mode is \u0022public\u0022",
  "statusCode": 400
}
```

#### Too many entries response

Request body exceeds the 100-member maximum.

```json
{
  "error": "Bad Request",
  "message": "[request body.entries]: array size is [101], but cannot be greater than [100]",
  "statusCode": 400
}
```

#### Conversation not found response

```json
{
  "attributes": {
    "trace_id": "8d4f2a3b-1c5e-4a9b-9f0d-2e6c1a3d4f5e"
  },
  "error": "Not Found",
  "message": "Conversation my-conversation-id not found",
  "statusCode": 404
}
```