Automatic rotation gives a secret a new, randomly generated value on a schedule you choose. Each rotation is saved as a new version, recorded in your audit log, and picked up by your machines on their next read. Rotation is switched on per secret, in the environment you are in.
Rotate a new secret#
In an environment, select the
+at the top right of the secrets table and choose Single-value.Pick the value's type and name the secret.
Switch on Automatic rotation. The value box is covered: the value is generated for you, now and on every rotation.
Choose the schedule and how the value is generated, then save.
For a structured secret, switch on Rotate on each field that should rotate. Each rotating field is generated by its own type, and one schedule, shown under the fields, covers all of them. Fields you leave off keep the value you type.
Rotate an existing secret#
Open the secret's row menu and choose Rotation.
Switch on Automatic rotation and choose the schedule and the generated value. For a structured secret, tick the fields that should rotate.
Select Turn on.
Schedules#
Schedule | When it rotates |
|---|---|
Interval | Every so many minutes, hours, or days, from 5 minutes to 30 days, counted from the last rotation. |
Weekly | On the days you pick, at a time of day. The time is in the time zone of the browser you saved it from, shown under the days, and it stays in that time zone whoever changes the secret later. |
What each type generates#
The generated value always matches the secret's type, and the dialog shows an example of what it makes.
Type | Generated value |
|---|---|
String, Password, Token | Random characters, at a length you set, from the sets you pick: A to Z, a to z, 0 to 9, and symbols. Or a UUID. |
Hex | Random bytes, as many as you set, written as hex. |
Base64, HMAC | Random bytes, as many as you set, written as base64. |
UUID | A new random UUID. |
Integer | A whole number between the minimum and maximum you set. |
Decimal | A number between the minimum and maximum you set, with the number of decimal places you set. |
Boolean, JSON, JSON5, YAML, XML, email, and URL values can't be generated, so secrets and fields of those types can't rotate.
While a secret rotates#
A rotating secret shows a rotation mark after its name. Point at it to see its schedule and when it rotates next.
Every rotation is a new version, so Version History lists each one and you can reveal any of them. The rotation owns the value: Edit value and reverting are not offered for a rotating value until rotation is switched off. On a structured secret, the fields that don't rotate can still be edited.
Machines get the new value on their next read. A command started with ratel run --watch restarts with it, and an SDK reading the secret live sees it change. Each rotation is recorded in your audit log, so a webhook subscribed to rotations hears about it as it happens.
Rotations happen while your Burrow is running. If it was off when one came due, it rotates once when it starts again, and the next rotation is counted from then. If a rotation fails, the rotation mark turns red with the reason, the failure is recorded in your audit log, and it is tried again a few minutes later.
Linked copies#
Creating a rotating secret with Also set in ticked gives each linked copy the same starting value and the same rotation settings. From the first rotation on, each copy generates its own values, so your environments never share them.
Change or switch off rotation#
Open Rotation from the secret's row menu. It shows when the secret last rotated and when it rotates next.
Change the schedule or the generated value and select Save. Saving doesn't rotate: the current value stays, and the next rotation follows the new schedule. To stop rotating, switch off Automatic rotation and select Turn off. The current value stays until someone changes it, and the secret can be edited by hand again.