For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

DigitalOcean Secrets Manager uses immutable versions to track changes to a secret without requiring applications to reference a different secret name. Rotation is the broader process of replacing a credential and moving applications to the new value.

Secret Versions

A version represents the complete set of key-value pairs stored for a secret at a specific point in time. When you create a secret, Secrets Manager creates its initial version. Every update creates a new immutable version. Applications continue to reference the same secret name as new versions are created.

Active Version

The newest version is the active version. When you retrieve a secret without specifying a version number, Secrets Manager returns the values from the active version.

After you update a secret:

• Secrets Manager creates a new version.
• The new version becomes active.
• Applications continue to use the same secret name.
• Future requests return the values from the new version.

Version numbers are available in the DigitalOcean Control Panel and the API. The doctl secrets list command shows the current version number. To list the retained versions of a secret, run doctl secrets list-versions:

doctl secrets list-versions app-database --region nyc3

Replace app-database with the secret name and nyc3 with the region where the secret is stored. The output shows the version number, creation time, and update time for each retained version. This command does not change the active version.

Version Retention

Secrets Manager retains the five most recent versions of a secret. When you create a sixth version, Secrets Manager removes the oldest retained version from the version history, and you can no longer retrieve it. To retrieve a retained version, specify its version number. Do not use version history as a long-term backup.

Revert to a Previous Version

You can revert a secret to one of its retained versions in the DigitalOcean Control Panel or with the API. Reverting does not reactivate or modify the previous version. Secrets Manager copies its values into a new version, which then becomes active. This preserves the immutable version history. Applications continue to use the same secret name.

Delete a Secret

You cannot delete individual secret versions. Deleting a secret soft-deletes the whole secret, including its retained versions. A soft-deleted secret no longer appears when you list or retrieve secrets, but you can restore it within 7 days in the Control Panel or with doctl secrets restore. After 7 days, Secrets Manager permanently deletes it.

Credential Rotation

Credential rotation replaces an existing password, token, API key, or other credential with a new value. Updating a value in Secrets Manager does not automatically change the credential in the system that validates it.

For example, rotating a database password generally requires you to:

1. Create or update the password in the database.
2. Update the corresponding value in Secrets Manager.
3. Confirm that the application receives and can use the new value.
4. Revoke the previous database password.

Unless an integration explicitly automates both sides of the change, you are responsible for coordinating the source credential and the value stored in Secrets Manager.

Recommended Rotation Sequence

When the backing system supports overlapping credentials:

1. Create a replacement credential in the system that validates it.
2. Update the corresponding value in Secrets Manager.
3. Deploy the application with the new version of the secret.
4. Verify that the application can use the replacement credential.
5. Revoke the previous credential.

Maintaining an overlap between the old and new credentials reduces the risk of an application outage during rotation. If the backing system does not support overlapping credentials, plan for the possibility of a brief interruption while the application receives the new value.

Related Topics

• Manage Secrets in the Control Panel
• Manage Secrets with doctl
• Secrets Manager Features
• Secrets Manager Limits