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,50 @@
+= AI Gateway Secret Management
+:description: Describes 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]. 
+
+== 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.
+* Secrets are backed by the Secrets 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.
+--
++
+You cannot edit the *ID* field (the secret identifier).
+
+. Click *Save*.
@@ -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
 

@@ -10,5 +10,4 @@ Redpanda Cloud also uses _static secrets_, stored in either the
 https://aws.amazon.com/secrets-manager/[AWS Secrets Manager^] or
 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.
+data plane account or network. They stay securely stored in AWS Secrets Manager or GCP Secret Manager.