WIP: adp: add authorization docs

modules/ai-agents/pages/agents/concepts.adoc

@@ -140,6 +140,8 @@ When context exceeds the limit, the oldest tool results get truncated, the agent
 
 Design workflows to complete within context limits. Avoid unbounded tool chaining.
 
+include::partial$service-account-authorization.adoc[]
+
 == Next steps
 
 * xref:ai-agents:agents/architecture-patterns.adoc[]

modules/ai-agents/pages/agents/create-agent.adoc

@@ -210,9 +210,9 @@ The updated metadata appears immediately at `\https://your-agent-url/.well-known
 
 . Configure the service account name (optional):
 +
-* Default pattern: `<cluster-type>-<cluster-id>-agent-<agent-name>-sa`
-* Custom name: 3-128 characters, cannot contain `<` or `>` characters
-* This service account authenticates the agent with cluster resources
+A service account is automatically created to authenticate your agent with cluster resources. The default name follows the pattern `cluster-<cluster-id>-agent-<agent-name>-sa`. You can customize this name (3-128 characters, cannot contain `<` or `>` characters).
++
+For details about default permissions and how to manage service accounts, see xref:ai-agents:agents/concepts.adoc#service-account-authorization[Service account authorization].
 
 . Click *Create Agent*.
 

modules/ai-agents/pages/agents/quickstart.adoc

@@ -104,6 +104,8 @@ Response format:
 * *Max Iterations*: `30` (allows multiple tool calls per request)
 
 . Review your configuration and click *Create Agent*.
++
+TIP: A service account is automatically created to authenticate your agent with cluster resources. For details about default permissions and how to manage service accounts, see xref:ai-agents:agents/concepts.adoc#service-account-authorization[Service account authorization].
 
 . Wait for the agent status to change from *Starting* to *Running*.
 

modules/ai-agents/pages/mcp/remote/concepts.adoc

@@ -37,6 +37,8 @@ MCP servers automatically emit OpenTelemetry traces for monitoring and debugging
 
 To monitor MCP server activity, consume traces, and debug failures, see xref:ai-agents:mcp/remote/monitor-mcp-servers.adoc[].
 
+include::partial$service-account-authorization.adoc[]
+
 == Next steps
 
 * xref:ai-agents:mcp/remote/create-tool.adoc[]

modules/ai-agents/pages/mcp/remote/quickstart.adoc

@@ -191,12 +191,7 @@ This page shows a list of existing servers.
 * *Description*: Explain what the server does. For example, `Generates fake user event data and publishes it to Redpanda topics`.
 * *Tags*: Add key/value tags such as `owner=platform` or `env=demo`. The tag names `service_account_id` and `secret_id` are reserved and cannot be used.
 * *Resources*: Choose a size (XSmall / Small / Medium / Large / XLarge). Larger sizes allow more concurrent requests and faster processing, but cost more. You can change this later.
-* *Service Account*: A service account is automatically created for authenticating the MCP server to your cluster. The name is pre-filled. You can customize this name or keep the default.
-+
-[NOTE]
-====
-Service accounts authenticate MCP server requests to your Redpanda cluster. The service account has editor permissions to the cluster, allowing it to perform operations like reading and writing data, managing topics, and accessing cluster resources. Service account credentials are stored in the xref:develop:connect/configuration/secret-management.adoc[Secrets Store] with the ID `SERVICE_ACCOUNT_<mcp-server-id>` and scope set to *MCP server*.
-====
+* *Service Account*: A service account is automatically created for authenticating the MCP server to your cluster. The name is pre-filled but you can customize it. For details about default permissions and how to manage service accounts, see xref:ai-agents:mcp/remote/concepts.adoc#service-account-authorization[Service account authorization].
 
 . Click *Next* to define tools.
 +

modules/ai-agents/partials/service-account-authorization.adoc

@@ -0,0 +1,61 @@
+[[service-account-authorization]]
+== Service account authorization
+
+When you create a glossterm:mcp-server[] or glossterm:ai-agent[], Redpanda Cloud automatically creates a glossterm:service-account[] to glossterm:authentication[authenticate] requests to your glossterm:cluster[].
+
+=== Default configuration
+
+The service account is created with:
+
+* *Name*: Pre-filled as `cluster-<cluster-id>-<resource-type>-<resource-name>-sa`, where `sa` stands for service account. For example:
+** MCP server: `cluster-d5tp5kntujt599ksadgg-mcp-my-test-server-sa`
+** AI agent: `cluster-d5tp5kntujt599ksadgg-agent-my-agent-sa`
++
+You can customize this name during creation.
+
+* *Role binding*: Cluster scope with Writer role for the cluster where you created the resource. This allows the resource to read and write data, manage glossterm:topic[,topics], and access cluster resources.
+
+=== Manage service accounts
+
+You can view and manage service accounts created for MCP servers and AI agents in *Organization* > *IAM* > *Service accounts*.
+
+The Organization IAM page shows additional details not visible during creation:
+
+[cols="1,2", options="header"]
+|===
+|Field |Description
+
+|Client ID
+|Unique identifier for OAuth2 authentication
+
+|Description
+|Optional description of the service account
+
+|Created at
+|Timestamp when the service account was created
+
+|Updated at
+|Timestamp of the last modification
+|===
+
+From this page you can:
+
+* Edit the service account name or description
+* View and manage role bindings
+* Rotate credentials
+* Delete the service account
+
+[NOTE]
+====
+Deleting a service account removes authentication for the associated MCP server or AI agent. The resource can no longer access cluster data.
+====
+
+=== Customize role bindings
+
+The default Writer role provides broad access suitable for most use cases. If you need more restrictive permissions:
+
+. Exit the cluster. Navigate to *Organization IAM * > *Service accounts*.
+. Find the service account for your resource.
+. Edit the role bindings to use a more restrictive role or scope.
+
+For more about roles and permissions, see xref:security:authorization/rbac/rbac.adoc[Role-based access control].