Update an agent's access control list

Base URL: https://{kibana_url}

PUT /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 authorization

Privileges agentBuilder:manageAgents

Path parameters

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).

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

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

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" }
  ]
}

curl Shell

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" }
    ]
  }'

Response

No example

{
  "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
}

{
  "attributes": {
    "trace_id": "8d4f2a3b-1c5e-4a9b-9f0d-2e6c1a3d4f5e"
  },
  "error": "Not Found",
  "message": "Agent custom-agent-id not found",
  "statusCode": 404
}

Request Console 1 / 2 languages

Submit an empty entries list to remove all custom grants. Access then falls back to the agent's access-control mode.

Console Kibana Dev Tools

PUT kbn:/api/agent_builder/agents/ID/access_control
{
  "entries": []
}

Generated from the API spec

curl Shell

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": []
  }'

Generated from the API spec

Response

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"
    }
  ]
}

{
  "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
}

{
  "attributes": {
    "trace_id": "8d4f2a3b-1c5e-4a9b-9f0d-2e6c1a3d4f5e"
  },
  "error": "Not Found",
  "message": "Agent custom-agent-id not found",
  "statusCode": 404
}

Request Console 1 / 2 languages

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).

Console Kibana Dev Tools

PUT kbn:/api/agent_builder/agents/ID/access_control
{
  "entries": [
    {
      "id": "u_alice_profile_uid",
      "role": "editor",
      "type": "user"
    },
    {
      "id": "u_bob_profile_uid",
      "role": "user",
      "type": "user"
    }
  ]
}

Generated from the API spec

curl Shell

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": [
      {
        "id": "u_alice_profile_uid",
        "role": "editor",
        "type": "user"
      },
      {
        "id": "u_bob_profile_uid",
        "role": "user",
        "type": "user"
      }
    ]
  }'

Generated from the API spec

Response

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"
    }
  ]
}

{
  "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
}

{
  "attributes": {
    "trace_id": "8d4f2a3b-1c5e-4a9b-9f0d-2e6c1a3d4f5e"
  },
  "error": "Not Found",
  "message": "Agent custom-agent-id not found",
  "statusCode": 404
}