---
title: Permissions and access control in Elastic Agent Builder
description: Learn how to configure security roles, API keys, and privileges for Agent Builder.
url: https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/permissions
products:
  - Elastic Cloud Serverless
  - Elastic Observability
  - Elastic Security
  - Elasticsearch
  - Kibana
applies_to:
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.3, Preview in 9.2
---

# Permissions and access control in Elastic Agent Builder
Use this page to learn how to configure security roles and API keys for Elastic Agent Builder. Understanding these privileges helps you control who can use agents, which tools they can access, and what data they can query.
<admonition title="Admonition">
  This feature requires the appropriate Elastic Stack [subscription](https://www.elastic.co/pricing) or Serverless [project feature tier](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/deploy-manage/deploy/elastic-cloud/project-settings).
</admonition>


## Required privileges

Elastic Agent Builder requires privileges at three levels:
- [Kibana feature access](#kib-privileges)
- [Elasticsearch cluster access](#es-cluster-privileges)
- [Elasticsearch index access](#es-index-privileges)


### Kibana privileges

Elastic Agent Builder access control is managed by the `agentBuilder` Kibana feature. Assign either `Read` or `All` based on what users need to do.
<applies-switch>
  <applies-item title="{ stack: ga 9.4+, serverless: ga }" applies-to="Elastic Cloud Serverless: Generally available, Elastic Stack: Generally available since 9.4">
    #### `Read`Grants access to:

    - Use agents
    - Send chat messages
    - View tools
    - View skills <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
    - Access conversations
    - Manage OAuth MCP clients for the [Elastic Agent Builder MCP server](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/mcp-server) <applies-to>Elastic Cloud Serverless: Generally available</applies-to>
    Instead of `All`, you can pair `Read` with individual sub-features for more granular control over what users can manage:
    - `Manage agents`: Create, update, or delete custom agents.
    - `Manage tools`: Create, update, or delete custom tools.
    - `Manage skills` <applies-to>Elastic Stack: Generally available since 9.4</applies-to>: Create, update, or delete custom skills.


    #### `All`The broadest access level. Grants everything in `Read`, plus the ability to:

    - Create, update, or delete custom agents
    - Create, update, or delete custom tools
    - Create, update, or delete custom skills <applies-to>Elastic Stack: Generally available since 9.4</applies-to>
    Includes all management sub-features by default.
  </applies-item>

  <applies-item title="{ stack: ga 9.2-9.3 }" applies-to="Elastic Stack: Generally available from 9.2 to 9.3">
    #### `Read`Required to use agents, send chat messages, view tools, and access conversations.


    #### `All`The broadest access level. Grants everything in `Read`, plus the ability to create, update, or delete custom agents and tools.
  </applies-item>
</applies-switch>

<note>
  If the agent uses AI connectors, also grant `Read` access to the Actions and Connectors feature.
</note>

Learn more about [Kibana privileges](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges).

### Elasticsearch cluster privileges

Elastic Agent Builder requires cluster-level privileges for AI-powered query generation:
- `monitor_inference`: Required when the agent uses an AI connector that calls the Elasticsearch Inference API (such as the Elastic default LLM or other AI connectors configured to use the Inference API). The built-in tools `search` and `generate_esql`, as well as [index search tools](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/tools/index-search-tools), use this API to generate queries from natural language. This privilege is not required when the agent uses other Kibana GenAI connectors.

Learn more about [cluster privileges](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html#privileges-list-cluster).

### Elasticsearch index privileges

Tools execute queries against Elasticsearch indices as the current user. Required privileges depend on which indices the tools access:
- `read`: Required for tools that query data.
- `view_index_metadata`: Required for tools that inspect index structure. Also required for the built-in `search` tool and [index search tools](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/tools/index-search-tools), which might use index exploration capabilities internally.

Learn more about [index privileges](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/elasticsearch/security-privileges#privileges-list-indices).

#### Read trace data

<applies-to>
  - Elastic Cloud Serverless: Generally available
  - Elastic Stack: Generally available since 9.5
</applies-to>

Elastic Agent Builder can [collect agent traces](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/collect-traces) into your Elasticsearch deployment. Trace data is stored in the `traces-agent_builder.otel-*` data stream. To read it, a role needs `read` and `view_index_metadata` on that pattern.
Access is granted at the index level. Any user who can read these data streams can read all collected traces, so trace access is not scoped per user. To control who can read traces, configure index privileges through roles in **Stack Management → Roles**.

## Conversation access control

<applies-to>
  - Elastic Cloud Serverless: Preview
  - Elastic Stack: Planned
</applies-to>

The Kibana privileges described above control who can use Elastic Agent Builder at all. Individual conversations have a second layer of access control on top of that, so the owner of a conversation can decide who else can read it.
Conversations are private by default. Only the user who created a conversation, its owner, can see it.

### Access modes

An owner can put a conversation into one of two access modes:
- `private`: only the owner and the users listed as members can read and continue the conversation. This is the default.
- `public`: any user who can access the conversation's agent can read and continue it. Public conversations also appear in those users' conversation lists.

Members apply to private conversations only. A public conversation cannot have members.
A conversation belongs to the Kibana space it was created in. Sharing does not make it visible from another space.

### The member role

Users you share a conversation with are added as members. `member` is the only available role. It grants two things:
- Read the conversation, including its full history.
- Continue the conversation by sending new messages.

Members cannot rename the conversation, delete it, or change who it is shared with.
You can share with individual users only. Granting access to an Elasticsearch role is not supported.
Members are identified by their Kibana user profile ID, not by username. A user who has never logged in to Kibana has no profile and cannot be added.

### Who can do what


| Action            | Owner | Member | Other users                        |
|-------------------|-------|--------|------------------------------------|
| Read and continue | Yes   | Yes    | Only if the conversation is public |
| Rename            | Yes   | No     | No                                 |
| Delete            | Yes   | No     | No                                 |
| Change sharing    | Yes   | No     | No                                 |

A user with full cluster privileges, such as a superuser, can also rename or delete a `public` conversation they do not own. This does not extend to `private` conversations, even ones shared with them, and it never includes changing who a conversation is shared with.

### Sharing does not bypass privileges

Sharing a conversation grants access to that conversation only. It does not grant any privilege the user does not already have.
A member still needs:
- The `agentBuilder` Kibana `Read` privilege.
- Access to the agent the conversation uses.
- Access to the space the conversation belongs to.

Access to the agent is checked every time a conversation is read, and this applies to the owner as well. If anyone loses access to a conversation's agent, or the agent is deleted, the conversation stops being readable for them and disappears from their conversation list.
Managing sharing needs only the `Read` privilege plus ownership. There is no separate sharing privilege, and no write privilege is involved.
When a user cannot access a conversation, Elastic Agent Builder reports it as not found rather than as a permissions error. This is deliberate, so that users cannot detect the existence of conversations they cannot read.
To share a conversation, use the [Kibana API](/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/kibana-api#update-conversation-access-control).

## Grant access

You can grant users access to Elastic Agent Builder using these methods:
- [Roles](#grant-access-with-roles) to bundle privileges for users.
- [API keys](#grant-access-with-api-keys) for programmatic access.
- [Spaces](#working-with-spaces) to scope access to specific environments.


### Grant access with roles

[Roles](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles) are Elasticsearch security constructs that bundle together Kibana feature privileges and Elasticsearch privileges. To grant users access to Elastic Agent Builder, create a role that includes the required privileges.
<note>
  When configuring roles in the Kibana UI, Elastic Agent Builder privileges appear under **Analytics**. In Serverless Elasticsearch projects, they appear under **Elasticsearch**.
</note>

Example role for users who need full Elastic Agent Builder access:
```json
POST /_security/role/agent-builder-full
{
  "cluster": ["monitor_inference"],
  "indices": [
    {
      "names": ["logs-*", "metrics-*"],
      "privileges": ["read", "view_index_metadata"]
    }
  ],
  "applications": [
    {
      "application": "kibana-.kibana",
      "privileges": [
        "feature_agentBuilder.all", 
        "feature_actions.read"
      ],
      "resources": ["space:default"]
    }
  ]
}
```

<note applies-to="Elastic Cloud Serverless: Generally available, Elastic Stack: Generally available since 9.4">
  For granular access, pair `feature_agentBuilder.read` with only the sub-feature privileges needed. To learn more, refer to [Kibana privileges](#kib-privileges).
</note>

<admonition title="Permissions for MCP clients" applies-to="Elastic Cloud Serverless: Generally available">
  Roles also determine what an MCP client can do when it connects to the Elastic Agent Builder MCP server through OAuth. The MCP client inherits the permissions of the user who authorizes the connection. To learn more, refer to [OAuth for MCP clients](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/deploy-manage/app-connections/oauth-clients).
</admonition>


### Grant access with API keys

When using the Elastic Agent Builder APIs programmatically, authenticate with an API key that includes the required privileges.
Unlike roles, which use UI-friendly feature privilege names like `feature_agentBuilder.all`, API keys use the underlying API privilege names (`read_onechat`, `manage_onechat`). This is because API keys interact directly with the Kibana API layer rather than through the UI.
Refer to these pages for API key configuration examples:
- [MCP server](/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/mcp-server-api-keys#api-key-application-privileges)
- [Kibana API](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/kibana-api)

Learn more about [API keys](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/deploy-manage/api-keys/elasticsearch-api-keys).

### Working with spaces

Elastic Agent Builder respects Kibana spaces when enabled. Conversations, custom agents, and custom tools are scoped to the current space. Built-in agents are space-agnostic and are available in all spaces. The default Elastic AI Agent is an exception <applies-to>Elastic Stack: Generally available since 9.4</applies-to>: it is a standard persisted agent that is space-aware and automatically created per space.
When configuring roles or API keys, specify the space in the application privileges resources (for example, `"resources": ["space:production"]`). Users and API keys cannot access resources in other spaces.
Learn how to [Copy your MCP server URL](/elastic/docs-content/pull/8115/explore-analyze/ai-features/agent-builder/tools#mcp-server-access).
<important>
  When accessing Elastic Agent Builder APIs or the MCP server from a custom space, include the space name in the URL path: `https://<deployment>/s/<space-name>/api/agent_builder/...`The default space uses the standard URL format without `/s/<space-name>`.
</important>

Learn more about [Kibana Spaces](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/8115/deploy-manage/manage-spaces).