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 or Serverless project feature tier.
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.
Use the following tables to identify the Kibana feature privileges and Elasticsearch privileges required for each Elastic Agent Builder use case.
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, skills, and conversations. |
| Agent Builder: All | feature_agentBuilder.all |
Everything granted by Read, plus all Elastic Agent Builder management privileges. |
| Agent Builder > Management: Create and edit agents | 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 | 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 | 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.
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 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 and index privileges.
Conversations, custom agents, and custom tools are scoped to the current Kibana space. Built-in agents are available in all spaces. The default Elastic AI Agent is an exception
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/<space-name> before the API path. The default space does not use this prefix.
Learn more about Kibana Spaces.
After choosing privileges and space scope, assign them based on who or what needs access.
Use 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 are currently located under the Analytics section, not the Elasticsearch section.
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 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.