Skip to main content

​
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

​
Supported providers

​
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.
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

​
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
    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.
  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

​
Database credential rotations

For most providers, including Redis and API key providers such as AWS and Cloudflare, Infisical issues a new credential on each rotation and removes the old one once it has been replaced. Database rotations work differently. Infisical never creates or drops users in PostgreSQL, MySQL, Microsoft SQL Server, Oracle Database, MongoDB, or ClickHouse. Doing so would require broader privileges than rotation needs, and a new user wouldn’t inherit the grants your applications depend on. Instead, you create two users up front and name them in the rotation.

​
Why two users?

Each cycle, Infisical generates a new password for whichever of the two users isn’t currently active and maps it to your secrets. The other user’s password stays valid as a grace-period credential until the following cycle replaces it, which is what gives the rotation its overlap. Infisical changes passwords in place, so with a single user it would overwrite the credential currently in use and lock out every client still holding the old password. The cycle never needs more than two users, which is why the configuration form has fixed Database Username 1 and Database Username 2 fields.

​
Who connects as the two users?

Your applications do. The pair backs one rotating credential: Infisical maps the active username and password to the secrets you choose, and your application connects as whichever user is currently active by reading those secrets. Grant both users the same privileges, since either one may be the active credential at any time, and let Infisical be the only thing that sets their passwords. The one user you can’t name is the one your app connection authenticates with, because rotating its password would break the connection that performs the rotation.

​
Rotating several credentials

Create a separate rotation for each credential you need, each with its own pair of users. A rotation produces a single active credential, so a database serving three applications that need independent credentials needs three rotations and six users. Two rotations must not share a pair of users, as each would overwrite the other’s passwords. If you want credentials issued per identity and revoked after a short lease, rather than one shared credential that changes on a schedule, use a dynamic secret instead.

​
Get alerted when a rotation fails

If a scheduled rotation fails after all of its retries, the rotation’s failure alert notifies your team by email, Slack, webhook, or PagerDuty.
  • If you create a rotation in the Infisical UI and can edit secret rotations in its environment and path, the alert is on by default, with an email to the project’s admins
  • If a rotation existed before failure alerts were available, it has the same alert
  • If a manual rotation fails, Infisical shows the error right away and doesn’t send an alert
  • Project admins get an in-app notification when a scheduled rotation fails, even if the alert is off
To set up or change a rotation’s alert, you need permission to edit secret rotations in the rotation’s environment and path.
1
For a new rotation, go to your project’s secrets overview and select Add New > Add Secret Rotation. For an existing rotation, select Edit on the rotation’s row.
2
Go to the Alerts step and make sure Alert on Rotation Failure is on. If you’re editing a rotation, select Alerts under Sections to go straight to it.
3
Select Add channel and set up at least one notification channel. The Project Admins recipient emails members who have the Admin role directly on the project. If someone is an admin only through a group, add the group as a recipient too.
4
For a new rotation, select Create secret rotation on the Review step. For an existing rotation, select Save.
If you create rotations through the API, create each rotation’s alert with the Create alert endpoint, using secret.rotation as the resource type, the rotation’s ID as the resource ID, and secret.rotation.failed as the event.