Secret Rotation - Infisical

Introduction

Secret rotation is a security best practice that involves systematically updating credentials and access tokens at regular intervals to minimize the risk of compromise. By proactively replacing existing secrets with new ones, organizations reduce the potential impact of credential theft or leakage.

Examples of rotated secrets include:

API keys and authentication tokens for cloud services and third-party integrations
Database credentials across production, staging, and development environments

How Rotation Works

Infisical supports two rotation models: Dual-Phase (used by most providers) and Single-Phase. Select a tab below to learn how each model works.

<Tabs> <Tab title="Dual-Phase"> Dual-phase rotation is the recommended approach that ensures zero downtime for your applications. This model systematically replaces secrets at regular intervals using an overlapping lifecycle that maintains continuous availability while enhancing your security posture.

    ### Visual Timeline

    ```mermaid
    gantt
        title Credential Lifecycle (Interval = 30 days)
        dateFormat  YYYY-MM-DD
        axisFormat %b %d

        section Credentials 1
        Active      :active, a1, 2023-01-01, 30d
        Inactive    :done, i1, after a1, 30d
        Revoked     :crit, r1, after i1, 30d

        section Credentials 2
        Active      :active, a2, 2023-01-31, 30d
        Inactive    :done, i2, after a2, 30d
        Revoked     :crit, r2, after i2, 30d

        section Credentials 3
        Active      :active, a3, 2023-03-02, 30d
        Inactive    :done, i3, after a3, 30d
        Revoked     :crit, r3, after i3, 30d
    ```

    ### Credential States

    Each set of credentials transitions through three distinct states:

    - **Active**: The primary credentials
    - **Inactive**: These credentials are still valid, but will be revoked in the next rotation 
    - **Revoked**: Permanently invalidated and deleted from the system

    ### Rotation Cycle Example (30-Day Interval)

    Using a __30-Day__ rotation interval as an example, here's how the process unfolds:

    1. __Day 0__
        - `Credential set 1` is issued and set to **Active**
        - Applications begin using this set for authentication

    2. __Day 30__
        - `Credential set 2` is issued and set to **Active**
        - `Credential set 1` transitions to **Inactive** but remains valid
        - New applications will utilize set 1, while existing applications with set 1 continue to work

        <Note>
            This overlapping validity period ensures that at any point during the active period of a credential set, you are guaranteed that retrieved credentials will be valid for the specified rotation period.
        </Note>

    3. __Day 60__
        - `Credential set 3` is issued and set to **Active**
        - `Credential set 2` transitions to **Inactive** but remains valid
        - `Credential set 1` is **Revoked** and securely deleted
        - By now, all applications should have transitioned to using set 2 or 3

    4. __Day 90__
        - `Credential set 4` is issued and set to **Active**
        - `Credential set 3` transitions to **Inactive** but remains valid
        - `Credential set 2` is **Revoked** and securely deleted
        - The cycle continues...

    ### Benefits

    - **Zero Downtime**: Applications always have valid credentials
    - **Grace Period**: The inactive period gives applications time to update to new credentials
    - **Reduced Risk**: Credentials are regularly cycled, limiting the impact of potential compromise
    - **Predictable Schedule**: Makes credential management more systematic and easier to automate

    ### Implementation Considerations

    - Choose a rotation interval appropriate for your security requirements and operational needs
    - Ensure your applications can handle credential updates gracefully
    - Monitor for applications still using credentials nearing revocation
</Tab>
<Tab title="Single-Phase">
    Some providers have technical limitations that prevent dual-phase rotation. These providers use **single-phase rotation**, which updates a single credential in place. When rotation occurs, old credentials become invalid immediately—there is no overlap period.

    This means that clients using the previous credentials will fail to authenticate until they retrieve the new credentials.

    <Warning>
        Single-phase rotation may cause brief service interruptions. For these providers, we recommend disabling auto-rotation and performing manual rotations during scheduled maintenance windows.
    </Warning>

    ### Why Single-Phase?

    Some credential providers have limitations that require single-phase rotation:

    - The third-party provider's API only supports managing one active credential set at a time
    - The specific use-case (such as personal login accounts) is inherently limited to a single active credential

    ### Recommendations

    When using single-phase rotation with service continuity requirements:

    - **Disable auto-rotation** and perform manual rotations during scheduled maintenance windows
    - **Coordinate with dependent services** to ensure they can quickly retrieve new credentials
    - **Monitor authentication failures** after rotation to detect any services that failed to update
</Tab>

</Tabs>