Update an agent's access control list

Server: https://{kibana_url}

PUT /api/agent_builder/agents/{id}/access_control
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.

Path Parameters

id string required: The unique identifier of the agent whose access control to update.

Request

entries [] object · max: 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

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

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

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

Request Console 1 / 2 languages

Console Kibana Dev Tools

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

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

Response

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

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

Request Console 1 / 2 languages

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

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

Response

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