Update an agent's access control list Technical Preview

PUT /api/agent_builder/agents/{id}/access_control
Api key auth

Spaces method and path for this operation:

put /s/{space_id}/api/agent_builder/agents/{id}/access_control

Refer to Spaces for more information.

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 authorization] Route required privileges: agentBuilder:manageAgents.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • id string Required

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

application/json

Body

  • entries array[object] 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).

    Not more than 100 elements.

    Hide entries attributes Show entries attributes object
    • id string Technical Preview

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

      Minimum length is 1, maximum length is 1024.

    • name string

      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.

      Minimum length is 1, maximum length is 1024.

    • role string 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 are user, editor, or manager.

    • type string Required

      Value is user.

Responses

  • 200 application/json

    Indicates a successful response

  • 400 application/json

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

  • 404 application/json

    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.

PUT /api/agent_builder/agents/{id}/access_control 
curl \
  -X PUT "${KIBANA_URL}/api/agent_builder/agents/{id}/access_control" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      { "type": "user", "id": "u_alice_profile_uid", "role": "editor" },
      { "type": "user", "id": "u_bob_profile_uid", "role": "user" }
    ]
  }'

PUT kbn://api/agent_builder/agents/{id}/access_control
{
  "entries": [
    { "type": "user", "id": "u_alice_profile_uid", "role": "editor" },
    { "type": "user", "id": "u_bob_profile_uid", "role": "user" }
  ]
}
Request examples
Submit an empty entries list to remove all custom grants. Access then falls back to the agent's access-control mode. 
{
  "entries": []
}
Example request granting two users access to the agent by their Kibana user profile uid — Alice as Editor (can update the agent configuration), Bob as User (can run the agent). 
{
  "entries": [
    {
      "id": "u_alice_profile_uid",
      "role": "editor",
      "type": "user"
    },
    {
      "id": "u_bob_profile_uid",
      "role": "user",
      "type": "user"
    }
  ]
}
Response examples (200)
Example response returning the persisted access control after the update. 
{
  "access_mode": "private",
  "entries": [
    {
      "added_at": "2026-02-11T10:15:00.000Z",
      "id": "u_alice_profile_uid",
      "role": "editor",
      "type": "user"
    },
    {
      "added_at": "2026-02-11T10:15:00.000Z",
      "id": "u_bob_profile_uid",
      "role": "user",
      "type": "user"
    }
  ]
}
Response examples (400)
The built-in Elastic default agent (`elastic-ai-agent`) cannot have custom access control — its access is governed by the platform, not per-agent grants. 
{
  "attributes": {
    "trace_id": "8d4f2a3b-1c5e-4a9b-9f0d-2e6c1a3d4f5e"
  },
  "error": "Bad Request",
  "message": "The default agent (elastic-ai-agent) does not support custom access controls.",
  "statusCode": 400
}
Request body exceeds the 100-entry maximum. 
{
  "error": "Bad Request",
  "message": "[request body.entries]: array size is [101], but cannot be greater than [100]",
  "statusCode": 400
}
Response examples (404) 
{
  "attributes": {
    "trace_id": "8d4f2a3b-1c5e-4a9b-9f0d-2e6c1a3d4f5e"
  },
  "error": "Not Found",
  "message": "Agent custom-agent-id not found",
  "statusCode": 404
}