docs: clarify single-instance vs dual-phase rotation per provider

IgorHorta · cursoragent · IgorHorta · commit bf00cdcd916c · 2026-02-03T11:09:43.000-03:00
- Add rotation behavior section to overview with provider comparison table
- Add dual-phase callout to 12 provider docs (PostgreSQL, MySQL, MSSQL, etc.)
- Update single-instance provider docs with warning callouts (Auth0, LDAP, Unix/Linux, Windows)
- Add FAQ explaining rotation type differences

Resolves SECRETS-99

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/docs/documentation/platform/secret-rotation/auth0-client-secret.mdx b/docs/documentation/platform/secret-rotation/auth0-client-secret.mdx
@@ -4,11 +4,11 @@ description: "Learn how to automatically rotate Auth0 Client Secrets."
 ---
 
 <Note>
-    Due to how Auth0 client secrets are rotated, retired credentials will not be able to
-    authenticate with Auth0 during their [inactive period](./overview#how-rotation-works).
+  **Rotation Type: [Single-Instance](/documentation/platform/secret-rotation/overview#single-instance-rotation)**
 
-    This is a limitation of the Auth0 platform and cannot be
-    rectified by Infisical.
+  This rotation updates a single credential set in place. Old credentials become invalid immediately upon rotation.
+
+  This is a limitation of the Auth0 platform and cannot be rectified by Infisical.
 </Note>
 
 ## Prerequisites
diff --git a/docs/documentation/platform/secret-rotation/aws-iam-user-secret.mdx b/docs/documentation/platform/secret-rotation/aws-iam-user-secret.mdx
@@ -3,6 +3,12 @@ title: "AWS IAM User"
 description: "Learn how to automatically rotate Access Key Id and Secret Key of AWS IAM Users."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 Infisical's AWS IAM User secret rotation capability lets you update the **Access key** and **Secret access key** credentials of a target IAM user from within Infisical
 at a specified interval or on-demand.
 
diff --git a/docs/documentation/platform/secret-rotation/azure-client-secret.mdx b/docs/documentation/platform/secret-rotation/azure-client-secret.mdx
@@ -3,6 +3,12 @@ title: "Azure Client Secret"
 description: "Learn how to automatically rotate Azure Client Secrets."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 - Create an [Azure Client Secret Connection](/integrations/app-connections/azure-client-secrets).
diff --git a/docs/documentation/platform/secret-rotation/databricks-service-principal-secret.mdx b/docs/documentation/platform/secret-rotation/databricks-service-principal-secret.mdx
@@ -3,6 +3,12 @@ title: "Databricks Service Principal Secret"
 description: "Learn how to automatically rotate Databricks Service Principal OAuth Secrets."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 - Ensure you've configured the service principal for rotation. See [Configure Permissions for Secret Rotation](/integrations/app-connections/databricks#configure-permissions-for-secret-rotation).
diff --git a/docs/documentation/platform/secret-rotation/dbt-service-token.mdx b/docs/documentation/platform/secret-rotation/dbt-service-token.mdx
@@ -3,6 +3,12 @@ title: "DBT Service Token"
 description: "Learn how to automatically rotate DBT Service Tokens."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 - Create a [DBT Connection](/integrations/app-connections/dbt).
diff --git a/docs/documentation/platform/secret-rotation/ldap-password.mdx b/docs/documentation/platform/secret-rotation/ldap-password.mdx
@@ -4,11 +4,11 @@ description: "Learn how to automatically rotate LDAP passwords."
 ---
 
 <Note>
-    Due to how LDAP passwords are rotated, retired credentials will not be able to
-    authenticate with the LDAP provider during their [inactive period](./overview#how-rotation-works).
+  **Rotation Type: [Single-Instance](/documentation/platform/secret-rotation/overview#single-instance-rotation)**
 
-    This is a limitation of the LDAP provider and cannot be
-    rectified by Infisical.
+  This rotation updates a single credential set in place. Old credentials become invalid immediately upon rotation.
+
+  This is a limitation of the LDAP provider and cannot be rectified by Infisical.
 </Note>
 
 ## Prerequisites
diff --git a/docs/documentation/platform/secret-rotation/mongodb-credentials.mdx b/docs/documentation/platform/secret-rotation/mongodb-credentials.mdx
@@ -3,6 +3,12 @@ title: "MongoDB Credentials Rotation"
 description: "Learn how to automatically rotate MongoDB credentials."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 1. Create a [MongoDB Connection](/integrations/app-connections/mongodb) with the required **Secret Rotation** permissions
diff --git a/docs/documentation/platform/secret-rotation/mssql-credentials.mdx b/docs/documentation/platform/secret-rotation/mssql-credentials.mdx
@@ -3,6 +3,12 @@ title: "Microsoft SQL Server Credentials Rotation"
 description: "Learn how to automatically rotate Microsoft SQL Server credentials."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 1. Create a [Microsoft SQL Server Connection](/integrations/app-connections/mssql) with the required **Secret Rotation** permissions
diff --git a/docs/documentation/platform/secret-rotation/mysql-credentials.mdx b/docs/documentation/platform/secret-rotation/mysql-credentials.mdx
@@ -3,6 +3,12 @@ title: "MySQL Credentials Rotation"
 description: "Learn how to automatically rotate MySQL credentials."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 1. Create a [MySQL Connection](/integrations/app-connections/mysql) with the required **Secret Rotation** permissions
diff --git a/docs/documentation/platform/secret-rotation/okta-client-secret.mdx b/docs/documentation/platform/secret-rotation/okta-client-secret.mdx
@@ -3,6 +3,12 @@ title: "Okta Client Secret"
 description: "Learn how to automatically rotate Okta Client Secrets."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 - Create an [Okta Connection](/integrations/app-connections/okta).
diff --git a/docs/documentation/platform/secret-rotation/openrouter-api-key.mdx b/docs/documentation/platform/secret-rotation/openrouter-api-key.mdx
@@ -3,6 +3,12 @@ title: "OpenRouter API Key"
 description: "Learn how to automatically rotate OpenRouter API keys."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 - Create an [OpenRouter Connection](/integrations/app-connections/openrouter) using a **Provisioning API key**. That connection is used to create and delete API keys on your behalf during rotation.
diff --git a/docs/documentation/platform/secret-rotation/oracledb-credentials.mdx b/docs/documentation/platform/secret-rotation/oracledb-credentials.mdx
@@ -3,6 +3,12 @@ title: "OracleDB Credentials Rotation"
 description: "Learn how to automatically rotate Oracle Database credentials."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 <Info>
     When working with SQL in Oracle databases, any values not surrounded by "quotes" will become UPPERCASE. Keep this in mind when creating users.
 </Info>
diff --git a/docs/documentation/platform/secret-rotation/overview.mdx b/docs/documentation/platform/secret-rotation/overview.mdx
@@ -15,7 +15,9 @@ Examples of rotated secrets include:
 
 ## How Rotation Works
 
-Secret Rotation systematically replaces secrets at regular intervals while ensuring zero downtime for your applications. This overlapping lifecycle approach maintains continuous availability while enhancing your security posture.
+Infisical supports two rotation models: **Dual-Phase** (used by most providers) and **Single-Instance**. This section describes dual-phase rotation, the recommended approach that ensures zero downtime. See [Single-Instance Rotation](#single-instance-rotation) for providers with limitations.
+
+Dual-phase rotation systematically replaces secrets at regular intervals while ensuring zero downtime for your applications. This overlapping lifecycle approach maintains continuous availability while enhancing your security posture.
 
 ### Visual Timeline
 
@@ -96,14 +98,51 @@ Using a __30-Day__ rotation interval as an example, here's how the process unfol
 - Ensure your applications can handle credential updates gracefully
 - Monitor for applications still using credentials nearing revocation
 
-## Infisical Secret Rotation Strategies
-
-- [PostgreSQL Credentials](./postgres-credentials)
-- [Microsoft SQL Server Credentials](./mssql-credentials)
+## Single-Instance Rotation
+
+Some providers have technical limitations that prevent dual-phase rotation. These providers use **single-instance rotation**, which updates a single credential in place. When rotation occurs, old credentials become invalid immediately—there is no overlap period.
+
+<Warning>
+Single-instance rotation may cause brief service interruptions. For these providers, we recommend disabling auto-rotation and performing manual rotations during scheduled maintenance windows.
+</Warning>
+
+## Provider Rotation Types
+
+| Provider | Rotation Type | Zero-Downtime |
+|----------|---------------|---------------|
+| [PostgreSQL Credentials](./postgres-credentials) | Dual-Phase | Yes |
+| [Microsoft SQL Server Credentials](./mssql-credentials) | Dual-Phase | Yes |
+| [MySQL Credentials](./mysql-credentials) | Dual-Phase | Yes |
+| [OracleDB Credentials](./oracledb-credentials) | Dual-Phase | Yes |
+| [MongoDB Credentials](./mongodb-credentials) | Dual-Phase | Yes |
+| [Redis Credentials](./redis-credentials) | Dual-Phase | Yes |
+| [AWS IAM User Secret](./aws-iam-user-secret) | Dual-Phase | Yes |
+| [Okta Client Secret](./okta-client-secret) | Dual-Phase | Yes |
+| [Azure Client Secret](./azure-client-secret) | Dual-Phase | Yes |
+| [Databricks Service Principal](./databricks-service-principal-secret) | Dual-Phase | Yes |
+| [DBT Service Token](./dbt-service-token) | Dual-Phase | Yes |
+| [OpenRouter API Key](./openrouter-api-key) | Dual-Phase | Yes |
+| [Auth0 Client Secret](./auth0-client-secret) | Single-Instance | No |
+| [LDAP Password](./ldap-password) | Single-Instance | No |
+| [Unix/Linux Local Account](./unix-linux-local-account) | Single-Instance | No |
+| [Windows Local Account](./windows-local-account) | Single-Instance | No |
 
 ## FAQ
 
 <AccordionGroup>
+    <Accordion title="What is the difference between single-instance and dual-phase rotation?">
+        **Dual-Phase Rotation:**
+        - Maintains two credential sets that cycle between active and inactive states
+        - New credentials are created before old ones are revoked
+        - Provides an overlap period where both credential sets are valid
+        - Enables zero-downtime rotation
+
+        **Single-Instance Rotation:**
+        - Rotates a single credential in place
+        - Old credentials become invalid immediately upon rotation
+        - May cause brief service interruptions during rotation
+        - Recommended to use manual rotation during maintenance windows
+    </Accordion>
     <Accordion title="Why do certain rotations only use a single credential set?">
         Some credential providers have limitations that affect rotation patterns:
 
diff --git a/docs/documentation/platform/secret-rotation/postgres-credentials.mdx b/docs/documentation/platform/secret-rotation/postgres-credentials.mdx
@@ -3,6 +3,12 @@ title: "PostgreSQL Credentials Rotation"
 description: "Learn how to automatically rotate PostgreSQL credentials."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 1. Create a [PostgreSQL Connection](/integrations/app-connections/postgres) with the required **Secret Rotation** permissions
diff --git a/docs/documentation/platform/secret-rotation/redis-credentials.mdx b/docs/documentation/platform/secret-rotation/redis-credentials.mdx
@@ -3,6 +3,12 @@ title: "Redis Credentials Rotation"
 description: "Learn how to automatically rotate Redis credentials."
 ---
 
+<Info>
+  **Rotation Type: Dual-Phase**
+
+  This rotation maintains two active credential sets with overlapping validity, ensuring zero-downtime during rotation cycles.
+</Info>
+
 ## Prerequisites
 
 1. Create a [Redis Connection](/integrations/app-connections/redis) with the required **Secret Rotation** permissions
diff --git a/docs/documentation/platform/secret-rotation/unix-linux-local-account.mdx b/docs/documentation/platform/secret-rotation/unix-linux-local-account.mdx
@@ -4,11 +4,11 @@ description: "Learn how to automatically rotate Unix/Linux local account passwor
 ---
 
 <Note>
-    Due to how Unix/Linux local account passwords are rotated, retired credentials will not be able to
-    authenticate with the SSH provider during their [inactive period](./overview#how-rotation-works).
+  **Rotation Type: [Single-Instance](/documentation/platform/secret-rotation/overview#single-instance-rotation)**
 
-    This is a limitation of the SSH provider and cannot be
-    rectified by Infisical.
+  This rotation updates a single credential set in place. Old credentials become invalid immediately upon rotation.
+
+  This is a limitation of the SSH provider and cannot be rectified by Infisical.
 </Note>
 
 ## Prerequisites
diff --git a/docs/documentation/platform/secret-rotation/windows-local-account.mdx b/docs/documentation/platform/secret-rotation/windows-local-account.mdx
@@ -4,10 +4,11 @@ description: "Learn how to automatically rotate Windows local account passwords
 ---
 
 <Note>
-    Due to how Windows local account passwords are rotated, retired credentials will not be able to
-    authenticate during their [inactive period](./overview#how-rotation-works).
+  **Rotation Type: [Single-Instance](/documentation/platform/secret-rotation/overview#single-instance-rotation)**
 
-    This is a limitation of the rotation mechanism and cannot be rectified by Infisical.
+  This rotation updates a single credential set in place. Old credentials become invalid immediately upon rotation.
+
+  This is a limitation of the rotation mechanism and cannot be rectified by Infisical.
 </Note>
 
 ## Prerequisites
