Type to search.

Update an agent's access control list

Base URL
https://{kibana_url}
  • PUT /api/agent_builder/agents/{id}/access_control
  • PUT /s/{space_id}/api/agent_builder/agents/{id}/access_control
Auth

Replace the per-agent access-control entries. Each entry grants one user a role on this agent. Identify the user by their Kibana user profile uid (id). Entries created before profile uids were adopted may use name (deprecated) instead. The agent owner, cluster admins, and anyone access control grants Manager can call this endpoint. Each call replaces the entire entries list — the most recent successful update wins. To learn more about agents, refer to the agents documentation.

Required privileges

Privileges agentBuilder:manageAgents

Path parameters

space_id string optional

An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.

id string required

The unique identifier of the agent whose access control to update.

Header parameters

kbn-xsrf string required

A required header to protect against CSRF attacks

Request body

entries object[] · max items: 100 required

Access-control entries to apply to the agent. Each entry has a type (for example user), a role, and either an id (the principal user profile uid, preferred) or a deprecated name (username).

id string · min length: 1 · max length: 1024

Stable identifier of the user to grant access to (Kibana user profile uid). Preferred over name.

name string · min length: 1 · max length: 1024

Case-sensitive Kibana username of the user to grant access to. Still supported, but id is preferred for new grants because a username cannot distinguish same-named users across authentication realms.

role enum required

Role granted to the principal. Roles are hierarchical: user allows viewing, listing, reading, and running the agent; editor adds updating the agent configuration; manager adds deleting the agent and managing its access control.

Values: user editor manager
type enum required
Values: user

Responses

200

Indicates a successful response

application/json
400

Bad Request — the request body failed validation, or the request targets the built-in Elastic default agent (which cannot have custom access control).

application/json
404

Not Found — no agent with this ID is visible to the caller, or the caller lacks write access. Matches the existing agentNotFound shape so unprivileged callers cannot probe for hidden agents.

application/json