redpanda-data · micheleRP · May 19, 2026 · May 19, 2026
@@ -67,6 +67,8 @@
 *** xref:governance:guardrails/cost-tracking.adoc[Cost Tracking]
 ** xref:governance:budgets.adoc[Token Budgets and Limits]
 ** xref:governance:kill-switch.adoc[Kill Switch]
+** xref:governance:permissions-overview.adoc[About ADP Permissions]
+** xref:governance:permissions-reference.adoc[ADP Permissions Reference]
 * xref:observability:index.adoc[Observability]
 ** xref:observability:concepts.adoc[Concepts]
 ** xref:observability:transcripts.adoc[Read a Transcript]

@@ -68,7 +68,7 @@ Before you register a BYOA agent, make sure you have:
 * An agent running in your own infrastructure with a reachable HTTPS endpoint.
 * The ability to add an HTTPS route at `/.well-known/agent-card.json` (or equivalent) on that endpoint. See <<a2a-endpoint-contract>>.
 * The agent instrumented with OpenTelemetry, emitting the minimum required spans contract. See xref:observability:byoa-telemetry.adoc[BYOA telemetry (OpenTelemetry)].
-* The right permission to create agents (`dataplane_adp_agent_create`).
+* The `dataplane_adp_agent_create` permission, granted by the Writer built-in role. See xref:governance:permissions-reference.adoc#agent-management-permissions[Agent management permissions].
 * A name for the agent that follows DNS-1123 conventions (1–63 characters, lowercase letters / numbers / hyphens, starting with a letter). The name is immutable once the agent is registered.
 
 [[a2a-endpoint-contract]]

@@ -358,9 +358,7 @@ The spend chart footer summarizes the selected view by cost bucket, including to
 |Gemini uses the `x-goog-api-key` header, not `Authorization`. If you're seeing 401s on Gemini, check that the client is sending the correct header. See xref:ai-gateway:connect-agent.adoc[Connect your agent].
 
 |Provider list empty or 403
-|Confirm your account has the `dataplane_adp_llmprovider_*` permissions in ADP.
-+
-// TODO: confirm the exact role/permission model once the standalone ADP UI launches.
+|Confirm your account has the `dataplane_adp_llmprovider_*` permissions in ADP. The Reader built-in role is the minimum required to list providers. The Writer role is required to create one. See xref:governance:permissions-reference.adoc#llm-provider-permissions[LLM provider permissions].
 |===
 
 // TODO: add screenshots of common error toasts once captured from the live environment.

@@ -439,7 +439,7 @@ AI Gateway returns standard HTTP status codes. The upstream provider's error bod
 
 === 403 Forbidden
 
-* The service account may lack the required roles. Ask an admin to grant `dataplane_adp_llmprovider_get` at minimum.
+* The service account may lack the required roles. Ask an admin to grant `dataplane_adp_llmprovider_get` at minimum to read provider config, and `dataplane_adp_llmprovider_invoke` to proxy LLM requests through AI Gateway. See xref:governance:permissions-reference.adoc#llm-provider-permissions[LLM provider permissions] or assign the LLMProviderInvoker built-in role for runtime-only access.
 * The provider may be disabled. Check the *Status* field on its *Connection* card.
 
 === Connection timeout or reset

@@ -20,7 +20,7 @@ Use this guide to:
 == Prerequisites
 
 * Access to the Agentic Data Plane
-* The `dataplane_adp_spending_get` permission to read spend, request, and token data
+* The `dataplane_adp_spending_get` permission to read spend, request, and token data, granted by both the Writer and Reader built-in roles. See xref:governance:permissions-reference.adoc#spending-permissions[Spending permissions].
 * At least one LLM provider or agent if you want non-empty charts and tables
 
 == Open the dashboard

@@ -0,0 +1,97 @@
+= About ADP Permissions
+:description: Understand how ADP permissions, built-in roles, and role bindings fit together to control access to AI Gateway, MCP, agents, pipelines, and governance APIs.
+:page-topic-type: concept
+:personas: platform_admin, evaluator, app_developer
+:learning-objective-1: Explain how ADP permissions, roles, and role bindings fit together
+:learning-objective-2: Differentiate between the Admin, Writer, Reader, and Invoker built-in roles
+:learning-objective-3: Identify which built-in role grants the permissions a user or service account needs
+
+// Source: `cloudv2` `pkg/permissions/permissions_constants.go`, `apps/aigw/internal/llm/authz.go`, `apps/aigw/internal/mcp/authz.go`, and `apps/ai-agent/internal/agent/authorization.go` on origin/main, verified 2026-05-18.
+// TODO: confirm screenshots of the role-binding flow in the Cloud UI once UX-790 (Console-side fine-grained authZ) ships.
+
+The Agentic Data Plane uses Redpanda Cloud's role-based access control (RBAC) to gate every API call. Each LLM provider, MCP server, agent, pipeline, knowledge base, and governance endpoint enforces a specific permission, and you assign permissions to users and service accounts by binding them to a role. This page explains the three-layer model so you can pick the right built-in role for a workload, or compose your own.
+
+After reading this page, you will be able to:
+
+* [ ] {learning-objective-1}
+* [ ] {learning-objective-2}
+* [ ] {learning-objective-3}
+
+== The three-layer model
+
+ADP authorization composes three pieces. Each layer answers a different question.
+
+* *Permission*: What action is allowed? A permission is a string like `dataplane_adp_llmprovider_invoke` that names exactly one operation on one resource type. The gRPC service that handles an API call checks the caller's permission set before executing.
+* *Role*: Which permissions go together? A role is a named bundle of permissions. ADP ships built-in roles for common access patterns (Admin, Writer, Reader, and a set of Invoker sub-roles), and you can define custom roles for more specific needs.
+* *Role binding*: Who gets the role, and where? A role binding attaches a role to a principal (user or service account) at a scope. Scopes range from the entire organization down to a single resource group or dataplane, so the same principal can have different permissions in different parts of your deployment.
+
+A successful API call requires all three: the caller must hold a role binding whose role contains the permission the endpoint enforces, at a scope that covers the resource being acted on.
+
+== ADP-namespaced permissions
+
+ADP permissions live in the following families, named by the namespace prefix:
+
+* `dataplane_adp_mcpserver_*`: Manage and call MCP servers (CRUD plus runtime operations like `tools_call` and `resources_read`).
+* `dataplane_adp_llmprovider_*`: Manage LLM providers and proxy LLM requests through AI Gateway. The `_invoke` permission is what your applications need at runtime.
+* `dataplane_adp_agent_*` and `dataplane_adp_agent_credential_*`: Manage declarative AI agents and the OIDC credentials issued to them.
+* `dataplane_adp_spending_*`: Read AI spending data for governance and cost reporting.
+* `dataplane_aiagent_a2a_*`: Invoke agent-to-agent (A2A) operations on running agents.
+* `dataplane_aigateway_*`: Manage enterprise AI Gateway features (rate limits, spend limits, routing rules, guardrails, model providers, audit, pricing, IAM).
+
+Two more families belong to Redpanda Connect resources that ADP uses:
+
+* `dataplane_pipeline_*`: Manage and invoke Redpanda Connect pipelines.
+* `dataplane_knowledgebase_*`: Manage retrieval-augmented generation knowledge bases.
+
+These permissions only resolve on clusters that have ADP enabled. Granting them to a principal on a non-ADP cluster has no effect.
+
+For the full list of permissions and which built-in role grants each one, see xref:governance:permissions-reference.adoc[ADP Permissions Reference].
+
+== Built-in roles
+
+ADP includes the following built-in roles. Admin, Writer, and Reader are general-purpose. The remaining roles are narrow Invoker roles for runtime-only access.
+
+[cols="1,3"]
+|===
+|Role |What it grants
+
+|*Admin*
+|Every permission, on every resource. Use for cluster operators who configure providers, agents, MCP servers, and pricing.
+
+|*Writer*
+|Full create, read, update, and delete access across every ADP-namespaced API (LLM provider, MCP server, agent, agent credential, AI Gateway, pipeline, knowledge base). Use for developers who need to build and modify ADP resources.
+
+|*Reader*
+|Read-only access (`_get` and `_list`) across the same APIs, plus MCP runtime read operations such as `resources_list` and `prompts_get`. No create, update, delete, or invoke. Use for auditors, evaluators, and stakeholders who need visibility without mutation rights.
+
+|*AIAgentInvoker*
+|A2A runtime only: `message_send`, `message_stream`, and the task lifecycle (`get`, `list`, `cancel`, `subscribe`). Use for service accounts that consume agents over A2A but should not manage them.
+
+|*MCPInvoker*
+|MCP runtime only: `initialize`, `ping`, the `resources_*` read methods, the `prompts_*` read methods, and `tools_list` / `tools_call`. No CRUD. Use for service accounts that call MCP tools without managing the servers themselves.
+
+|*LLMProviderInvoker*
+|A single permission: `dataplane_adp_llmprovider_invoke`. Use for applications that proxy LLM requests through AI Gateway but should not see or modify provider configuration.
+
+|*PipelineInvoker*
+|Runtime pipeline invocation only: `gateway_invoke`, `otlp_grpc_invoke`, `otlp_http_invoke`. Use for clients that produce telemetry or send data into Connect pipelines without managing them.
+|===
+
+Pick the narrowest role that covers a workload. For example, an application that only needs to call an LLM through AI Gateway should hold the LLMProviderInvoker role, not the Writer role.
+
+== Identity and impersonation
+
+ADP API calls authenticate as one of two identity types:
+
+* *User identity (OIDC)*: A human user signed in through Redpanda Cloud's OIDC provider. The Cloud UI uses this identity when an admin manages ADP resources interactively.
+* *Service account*: A non-human identity backed by OIDC client credentials. Applications, CI jobs, and `rpk ai` use service accounts.
+
+Account impersonation, which lets Redpanda Cloud's Console reuse a user's identity for Kafka API and Schema Registry calls, applies to those two subsystems only. ADP endpoints continue to authenticate clients directly through their OIDC tokens, regardless of how account impersonation is configured at the cluster level. See xref:redpanda-cloud:security:cloud-authentication.adoc#account-impersonation[Account impersonation] for the Kafka and Schema Registry flow.
+
+== Where ADP fits in Cloud RBAC
+
+ADP permissions are part of the same Cloud RBAC system that gates control-plane resources such as resource groups, networks, and clusters. The Admin, Writer, and Reader built-in roles each cover control-plane permissions, dataplane Kafka permissions, and ADP dataplane permissions in a single bundle, so a single role binding on the Writer role at the organization scope grants a developer access to every layer.
+
+== Related topics
+
+* xref:governance:permissions-reference.adoc[ADP Permissions Reference]