Secrets and versions
What a secret is made of, how its versions work, and which secrets the platform writes for you.
A secret is a name, a value stored as one or more versions, and the KMS key the versions are encrypted under. Apps and workflows find it by name; the CLI and the API address it by its id.
Fields
| Field | Values | Default |
|---|---|---|
name |
UPPER_SNAKE_CASE, starting with a letter, 1 to 128 characters. Cannot be changed. |
required |
keyId |
The KMS key the value is encrypted under: enabled, encrypt_decrypt. Cannot be changed. |
required in the API and CLI |
value or reference |
The value (at least one character), or a source reference for a synced secret. | one of the two is required |
environmentId |
The environment it belongs to, or null for the Default. Cannot be changed. |
null (Default) |
group |
Up to three lower-case segments separated by /, at most 122 characters, or null. |
Ungrouped; for a synced secret, see File secrets in groups |
description |
Up to 256 characters. | none |
scope, scopeRef |
organization, project or resource, and up to 500 characters naming which one. |
organization, none |
rotationIntervalDays |
1 to 3650, or null for no rotation policy. |
none |
The console pre-selects the organization's default key. scope and scopeRef are labels: they
grant nothing and limit nothing.
A name is unique in its environment, and once as a Default. The same name can exist once as the Default and once in each environment; see Environments.
Versions
Creating a secret stores its value as version 1. Each rotation stores the new value as the next number and retires the active version; nothing is overwritten or deleted. Exactly one version is active, and that is the one every consumer reads.
A rollback makes a retired version active again under its own number, and retires the version that
was active. So after rotating to v3 and rolling back to v2, v2 is active, and the next
rotation writes v4.
A running app or job keeps the value it was given. It gets the active version at its next deployment or run.
Rotation policy
rotationIntervalDays gives a secret a due date (rotatesAt), that many days after it was created,
last rotated or the interval last changed. The list's Rotation column shows the time left:
in 9d, amber within two weeks, Overdue 3d in red once past it, No policy without one. Nothing
rotates the value for you; when it is due, rotate it (see Rotate a secret).
Secrets the platform writes
- Synced secrets. A secret created from a source reference gets its versions from the source, and is refused for a manual rotation or rollback. See Sync a secret from a source.
- Source credentials. Connecting a source stores its credential as the secret
SOURCE_<NAME>_TOKEN. Deleting it is refused; disconnect the source instead. - Managed database passwords. Managed databases, caches and brokers file their generated
passwords as secrets (in the group
managed/<engine>, such asmanaged/postgres). - Error Tracking keys. A secret managed by Error Tracking shows Managed by Error Tracking
as its source. Error Tracking writes and rotates it: rotating, rolling back, editing its details
or promoting it here is refused with
409, and deleting it is refused while an app or CI environment still uses it. Granting it and moving it to another group with Move to group are not refused.