Update an agent's access control list

Base URL: https://{kibana_url}

PUT /api/agent_builder/agents/{id}/access_control

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

Authentication

Api key

Authorization: <value>

These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey

Basic

Authorization: Basic <credentials>

Path parameters

Header parameters

Request body

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

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
}

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

Required authorization

Authentication

Path parameters

Header parameters

Request body { }

Responses

Request body