# 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](file-secrets-in-groups.md) |
| `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](environments.md).

## 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](rotate-a-secret.md)).

## 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](sync-a-secret-from-a-source.md).
- **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.

## Related

- [Create a secret](create-a-secret.md)
- [Rotate a secret](rotate-a-secret.md)
- [Keys and encryption](keys-and-encryption.md)
