Secrets and groups

Every secret has a template. The template decides what fields it has, which of them are sensitive, and where the value is stored - which is why the create form asks you what kind of thing you are storing before it asks for the value.

Two storage behaviours, and the difference matters:

Stored as a secret

env, plain, note, json_blob, tls_certificate. These live in the secrets table, encrypted, and appear under Secrets.

Stored as infrastructure

ssh_login, database_url, aws_keys, kubeconfig. Creating one of these *registers a piece of infrastructure* - it appears under Infrastructure, gets an alias, and becomes reachable with shortspan ssh, db, aws, or k8s.

Fields marked non-sensitive - a hostname, a port, a region, a certificate's public half - are copied into metadata so they can be listed and searched without decrypting anything.

Every template and its fields are documented in Secret templates.

Secrets → New secret, then pick a template. Creation is a full page rather than a modal - storing a credential deserves more than a dialog you can dismiss by clicking beside it.

Requires the developer role. Each form shows the equivalent CLI command, so the console teaches the interface you will actually be using.

Updating a secret creates a new version; it never overwrites. The secret's page lists every version with who wrote it and when.

On Pro and above you can restore a previous version. A restore creates a *new* version whose value equals the old one, so the history stays append-only and the rollback is itself recorded.

A secret's page shows metadata by default. Revealing the value is an explicit action, requires the developer role, is rate limited, and is recorded in the audit log as a reveal rather than a read.

A group names a set of secrets so they can be injected together. It is what shortspan run <group> consumes, and it is the unit most applications actually need - one variable is rarely the whole configuration.

Groups carry a name, a description, and an environment label (production, staging, development, or custom). A group's page lists its members and lets you add or remove secrets in one edit.

Deleting a group leaves its secrets in place, ungrouped. A group is a label; deleting a label should never delete the things it was on.

1. 1

   Set the new value

   Update the secret. A new version is created; nothing is deleted.

2. 2

   Let it propagate

   Nothing is cached on any machine, so the next shortspan run uses the new value. Restart long-running processes that read the old one at boot.

3. 3

   Revoke at the source

   Deactivate the old API key, password, or certificate wherever it was issued. Until you do, the old value still works - Shortspan stores credentials, it does not mint them.

Notifications are sent when a rotation completes or fails, so a failed rotation does not quietly leave the old credential in place.