redpanda-data · micheleRP · Mar 11, 2026 · Mar 11, 2026 · Mar 11, 2026 · Mar 11, 2026
@@ -69,6 +69,7 @@
 *** xref:ai-agents:ai-gateway/gateway-architecture.adoc[Architecture]
 *** For Administrators
 **** xref:ai-agents:ai-gateway/admin/setup-guide.adoc[Setup Guide]
+**** xref:ai-agents:ai-gateway/admin/secret-management.adoc[Secret Management]
 *** For Builders
 **** xref:ai-agents:ai-gateway/builders/discover-gateways.adoc[Discover Gateways]
 **** xref:ai-agents:ai-gateway/builders/connect-your-agent.adoc[Connect Your Agent]

@@ -0,0 +1,67 @@
+= AI Gateway Secret Management
+:description: Understand how AI Gateway stores provider API keys in the Secrets Store and how to view, rotate, and manage them.
+:page-topic-type: how-to
+:personas: platform_admin
+:learning-objective-1: Understand how AI Gateway secrets are stored in the Secrets Store
+:learning-objective-2: View AI Gateway secrets in the Secrets Store UI
+:learning-objective-3: Rotate provider API keys
+
+include::ai-agents:partial$adp-la.adoc[]
+
+When you add a provider API key through the AI Gateway configuration UI, the key is automatically stored in the xref:security:secrets.adoc[Secrets Store]. Unlike Redpanda Connect or MCP Server secrets, which you create manually, AI Gateway secrets are created and managed for you.
+
+== How AI Gateway secrets work
+
+AI Gateway integrates with the Secrets Store to manage provider API keys securely:
+
+* When you add an API key to an LLM provider (through *AI Gateway* → *Providers* → select a provider → *Configuration* → *Add Configuration*), AI Gateway automatically creates a corresponding secret in the Secrets Store.
+* These secrets are labeled `managed-by:aigateway` in the Secrets Store.
+* Secrets are backed by the secret store used by the Redpanda Cloud data plane and never leave the data plane.
+* At runtime, the AI Gateway reads provider credentials directly from the Secrets Store.
+
+You can also edit AI Gateway secrets directly in the Secrets Store. The secret ID cannot be changed, but you can update the secret value, scopes, and tags.
+
+TIP: To create or delete provider API keys, use the AI Gateway provider configuration UI (*Agentic* → *AI Gateway* → *Providers* → select a provider → *Configuration*). To update an existing secret's value, scopes, or tags, go to the Secrets Store.
+
+== View AI Gateway secrets
+
+To see the secrets that AI Gateway has created:
+
+. In the Redpanda Cloud Console, open the *Secrets Store*.
+. Look for secrets with the *AI Gateway* scope label.
++
+These secrets are labeled `managed-by:aigateway` to distinguish them from secrets created manually for other services.
+
+== Edit AI Gateway secrets
+
+You can edit an AI Gateway secret directly in the Secrets Store:
+
+. Open the *Secrets Store*.
+. Select the secret you want to update.
+. Update any of the following fields:
++
+--
+* *Value*: The API key value. Leave empty to keep the existing value.
+* *Scopes*: The resources that can access this secret.
+* *Tags*: Key-value pairs for organizing and categorizing secrets.
+--
++
+The *ID* field (the secret identifier) cannot be changed.
+
+. Click *Save*.
+
+== Rotate provider API keys
+
+When you rotate a provider API key through the provider's *Configuration* tab, the corresponding Secrets Store entry is automatically updated.
+
+To rotate credentials without downtime:
+
+. Navigate to *Agentic* → *AI Gateway* → *Providers*, select the provider, and click *Configuration*.
+. Click *Add Configuration* to add a new API key (don't remove the old one yet).
+. Wait for the new key to propagate (approximately 5 minutes).
+. Verify the new key works by sending a test request through the gateway.
+. Remove the old API key.
+
+Each provider configuration supports multiple API keys. AI Gateway automatically load-balances across them, which allows zero-downtime rotation. For more details, see the credential rotation steps in xref:ai-gateway/admin/setup-guide.adoc[].
+
+For an overview of all secret scopes in Redpanda Cloud, see xref:security:secrets.adoc[].
@@ -31,7 +31,7 @@ Providers represent upstream services (Anthropic, OpenAI, Google AI) and associa
 . On the Configuration tab for the provider, click *Add configuration*.
 . Enter your API Key for the provider.
 +
-TIP: Store provider API keys securely. Each provider configuration can have multiple API keys for rotation and redundancy.
+NOTE: Provider API keys are automatically stored in the xref:security:secrets.adoc[Secrets Store] when you save the configuration. Each provider configuration supports multiple API keys for rotation and redundancy. For details, see xref:ai-gateway/admin/secret-management.adoc[].
 
 . Click *Save* to enable the provider.
 

@@ -222,7 +222,7 @@ curl https://api.redpanda.com/v1/gateways/${GATEWAY_ID}/ai-hub/preferences \
 
 == Manage provider credentials
 
-AI Hub gateways require provider credentials to route requests. Credentials are stored encrypted and shared across all gateways in your workspace.
+AI Hub gateways require provider credentials to route requests. Credentials are automatically stored in the xref:security:secrets.adoc[Secrets Store] and shared across all gateways in your workspace. For details on how AI Gateway manages secrets, see xref:ai-agents:ai-gateway/admin/secret-management.adoc[].
 
 === Add OpenAI credentials
 
@@ -265,7 +265,7 @@ To rotate credentials without downtime:
 . Test with a sample request to verify the new key works.
 . Delete the old API key.
 
-AI Gateway automatically load-balances across multiple API keys if you configure more than one per provider.
+When you rotate credentials, the corresponding entry in the Secrets Store is automatically updated. AI Gateway automatically load-balances across multiple API keys if you configure more than one per provider.
 
 === Verify credentials
 

@@ -12,3 +12,32 @@ https://cloud.google.com/secret-manager[GCP Secret Manager^] services. Static
 secrets managed through Redpanda Console never leave their corresponding
 data plane account or network. They stay securely stored in AWS Secrets Manager or
 GCP Secret Manager.
+
+== Secret scopes
+
+The Secrets Store organizes secrets by scope. Each scope corresponds to a Redpanda Cloud service that uses secrets:
+
+[cols="1,2,1"]
+|===
+| Scope | Description | Management
+
+| AI Gateway
+| Provider API keys for LLM providers (OpenAI, Anthropic, Google AI). Labeled `managed-by:aigateway` in the Secrets Store.
+| xref:ai-agents:ai-gateway/admin/secret-management.adoc[Automatic]
+
+| MCP Server
+| Secrets used by remote MCP server configurations.
+| Manual
+
+| AI Agent
+| Secrets used by AI agent configurations.
+| Manual
+
+| Cluster
+| Secrets used by the Redpanda cluster, such as Schema Registry credentials.
+| Manual
+
+| Redpanda Connect
+| Secrets referenced in pipeline configurations using the `$\{!secrets.<name>}` interpolation syntax.
+| xref:develop:connect/configuration/secret-management.adoc[Manual]
+|===