---
title: Permissions and access control in Elastic Agent Builder
description: Understand how Kibana feature privileges, Elasticsearch privileges, and spaces control access to Agent Builder.
url: https://www.elastic.co/elastic/docs-builder/docs/4047/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 understand the Elastic Agent Builder permission model and choose least-privilege access for users and programmatic clients. After choosing the required privileges, assign them to users with roles or to clients with API keys.
This feature requires the appropriate Elastic Stack [subscription](https://www.elastic.co/pricing) or Serverless [project feature tier](https://www.elastic.co/elastic/docs-builder/docs/4047/deploy-manage/deploy/elastic-cloud/project-settings).
## How permissions work
An Elastic Agent Builder request is allowed only when the user or client has access at every relevant layer:
- **Kibana feature privileges** control which Elastic Agent Builder, connector, and workflow operations the user or client can perform.
- **Elasticsearch cluster and index privileges** control whether agents and tools can use inference endpoints, query data, and inspect mappings.
- **Kibana space scope** controls which space-specific Elastic Agent Builder resources the user or client can access.
Not every operation requires every privilege. For example, a tool that queries an index requires index privileges, while `monitor_inference` is required only when an agent or tool calls the Elasticsearch Inference API.
## Privilege reference
Use the following tables to identify the Kibana feature privileges and Elasticsearch privileges required for each Elastic Agent Builder use case.
### Kibana feature privileges
In the role management UI, Kibana displays human-readable privilege names. Role descriptors and API keys use the corresponding application privilege identifiers. For these privileges, use `kibana-.kibana` as the application name and scope the application resource to the required space.
| Feature and UI privilege | Role and API key privilege | Grants |
|------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Agent Builder: Read** | `feature_agentBuilder.read` | Use agents, send chat messages, and view agents, tools, and conversations.Elastic Stack: Generally available since 9.4 Also view skills.On Serverless, also manage OAuth MCP clients for the [Elastic Agent Builder MCP server](https://www.elastic.co/elastic/docs-builder/docs/4047/explore-analyze/ai-features/agent-builder/mcp-server). |
| **Agent Builder: All** | `feature_agentBuilder.all` | Everything granted by **Read**, plus all Elastic Agent Builder management privileges. |
| **Agent Builder > Management: Create and edit agents** Elastic Stack: Generally available since 9.4 | `feature_agentBuilder.manage_agents` | Pair with **Read** to create, update, and delete custom agents without granting other management privileges. |
| **Agent Builder > Management: Create and edit custom tools** Elastic Stack: Generally available since 9.4 | `feature_agentBuilder.manage_tools` | Pair with **Read** to create, update, and delete custom tools without granting other management privileges. |
| **Agent Builder > Management: Create and edit skills** Elastic Stack: Generally available since 9.4 | `feature_agentBuilder.manage_skills` | Pair with **Read** to create, update, and delete custom skills without granting other management privileges. |
| **Actions and Connectors: Read** | `feature_actions.read` | Use agents that access Kibana connectors. |
| **Workflows: Read** | `feature_workflowsManagement.read` | Read workflows and workflow execution information. |
| **Workflows > Workflows Actions: Execute** | `feature_workflowsManagement.workflow_execute` | Run workflows. Also include **Workflows: Read** when the user or client must inspect workflows. |
| **Workflows: All** | `feature_workflowsManagement.all` | Create, update, delete, run, and read workflows and their executions. |
Learn more about [Kibana privileges](https://www.elastic.co/elastic/docs-builder/docs/4047/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-privileges).
### Elasticsearch privileges
Tools execute Elasticsearch requests with the privileges of the current user or API key. Assign only the cluster and index privileges required by the tools the principal can access.
| Scope | Privilege | When to use it |
|---------|-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Cluster | `monitor_inference` | Required when an agent uses an AI connector that calls the Elasticsearch Inference API, including the Elastic default LLM, or when a tool uses the Inference API to generate queries from natural language. The built-in `search` and `generate_esql` tools and [index search tools](https://www.elastic.co/elastic/docs-builder/docs/4047/explore-analyze/ai-features/agent-builder/tools/index-search-tools) use this API. This privilege is not required for other Kibana GenAI connectors. |
| Indices | `read` | Required for tools that query index data. Limit the assigned index patterns to the data the user or client needs. |
| Indices | `view_index_metadata` | Required for tools that inspect index mappings. The built-in `search` tool and index search tools might use this capability internally. |
Learn more about [cluster privileges](https://www.elastic.co/guide/en/elasticsearch/reference/current/security-privileges.html#privileges-list-cluster) and [index privileges](https://docs-v3-preview.elastic.dev/elastic/docs-builder/docs/4047/reference/elasticsearch/security-privileges#privileges-list-indices).
#### Read trace data
- Elastic Cloud Serverless: Generally available
- Elastic Stack: Generally available since 9.5
Elastic Agent Builder can [collect agent traces](https://www.elastic.co/elastic/docs-builder/docs/4047/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**.
### Kibana space scope
Conversations, custom agents, and custom tools are scoped to the current Kibana space. Built-in agents are available in all spaces.
Elastic Stack: Generally available since 9.4 The default Elastic AI Agent is an exception: it is a persisted, space-aware agent that is automatically created in each space.
In a role or API key descriptor, specify the space in the application privilege resource. For example, use `"resources": ["space:production"]` for the `production` space. Users and API keys cannot access resources in spaces outside their assigned resources.
When calling the Elastic Agent Builder APIs or MCP server in a custom space, include `/s/` before the API path. The default space does not use this prefix.
Learn more about [Kibana Spaces](https://www.elastic.co/elastic/docs-builder/docs/4047/deploy-manage/manage-spaces).
## Conversation access control
- Elastic Cloud Serverless: Preview
- Elastic Stack: Planned
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-builder/docs/4047/explore-analyze/ai-features/agent-builder/kibana-api#update-conversation-access-control).
## Configure access
After choosing privileges and space scope, assign them based on who or what needs access.
### Roles for users
Use [roles](https://www.elastic.co/elastic/docs-builder/docs/4047/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles) to bundle the required Kibana feature privileges and Elasticsearch privileges, then assign the roles to users. In the role management UI, choose the required space and feature privileges under **Kibana privileges**, and limit index privileges to the data the users need.
When configuring roles in the Kibana UI, Elastic Agent Builder privileges appear under **Analytics**. In Serverless Elasticsearch projects, they appear under **Elasticsearch**.
On Serverless, roles also determine what an MCP client can do when it connects to the Elastic Agent Builder MCP server through OAuth. The client inherits the permissions of the user who authorizes the connection. To learn more, refer to [OAuth for MCP clients](https://www.elastic.co/elastic/docs-builder/docs/4047/deploy-manage/app-connections/oauth-clients). Elastic Cloud Serverless: Generally available
### API keys for programmatic clients
Use API keys for custom clients, scripts, MCP clients, and A2A clients. API key role descriptors combine the same Kibana application privileges, Elasticsearch privileges, and space scope described on this page. An API key cannot grant privileges that its owner does not have.
Refer to [Create API keys for Elastic Agent Builder APIs](https://www.elastic.co/elastic/docs-builder/docs/4047/explore-analyze/ai-features/agent-builder/api-keys) for complete examples for read-only clients, management clients, and unrestricted development keys. To learn more about API key behavior and management, refer to [Elasticsearch API keys](https://www.elastic.co/elastic/docs-builder/docs/4047/deploy-manage/api-keys/elasticsearch-api-keys).