Secrets and versions

What a secret is made of, how its versions work, and which secrets the platform writes for you.

Last updated 18 November 2026View as Markdown

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 as managed/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.
Did this page help you?