Skip to main content

Secrets and folders

A secret is a credential Sneakers-PAM stores on your behalf: a password, a key, a token, or another sensitive value. Every secret keeps its full history — each past value stays available, not just the current one — so you can see what changed and when. Changing a secret's type (see Changing a secret's type) reads in that history as the change it actually was (old type to new, fields added, renamed or carried over), not just a list of fields that happen to differ.

A secret's type decides which fields it has, and some of them are required: a credential saved with a required field left empty is refused, naming the field, the same way an invalid choice on a drop-down field is. A secret that already had one empty from before this was enforced still opens and works; the next edit that saves that field is what completes it.

Some types get an editor of their own. A GitHub App secret takes the App's .pem file directly and checks it's the right kind of key before it's stored, and its page has a Replace private key action for when the key is rotated on GitHub. See Storing a GitHub App.

Secrets live in folders, and folders can be nested. A folder is where access control actually happens: who can see that a secret exists, who can reveal its value, who can approve a request for it, and who is just kept informed. A secret inherits its folder's rules unless it has its own. The top of your personal folder holds folders, not secrets, so the staff app doesn't offer it as a place for a secret: make a folder inside it first.

A secret can also be linked to one or more targets — the systems it actually protects, such as a server account or a service's own config. One SSH key can open a session on every host it's attached to, with no copies to keep in sync; attaching or detaching one target never disturbs the others. That link is what makes heartbeat and rotation possible: Sneakers-PAM can check the secret against each of its targets, and change them together.

A secret's own page lists its attached targets, with an Attach picker for adding another and a Detach button next to each one already there. Opening a terminal on an SSH Key or Password Account (SSH) secret goes straight to the only target when it has just one; with more than one attached, a short picker asks which to open the session on before it connects.

When the terminal can't connect yet, Open terminal stays in the secret's Actions menu, disabled, with the reason beside it:

  • Attach a target first. The secret has no target attached.
  • Its target doesn't connect over SSH. None of its targets uses an SSH connection.
  • Pin the target's host key first. None of its SSH targets has a pinned host key yet (see SSH host keys). Whoever may pin the target (a site admin, or the owner of a personal target) also gets Scan and pin host key… in the same menu. Anyone else is told an admin needs to pin it.

One SSH target with a pinned host key is enough to turn the action back on.

A target's own page, in turn, lists every secret attached to it — useful for seeing at a glance what else shares a host's credential before changing or deleting the target.

SSH host keys​

A target reached over SSH carries its own pinned host keys — the public keys that identify the real server, so a credential is never sent to an impostor. Pinning them is always a person's decision: a site admin pins any target, and the owner of a personal target pins their own (see Pinning SSH host keys). No token, agent or automated request — not even a site admin's — can add, change or clear a target's pins. A secret whose target has none of its host keys pinned yet can't heartbeat until a person pins one. Each attached target keeps its own pins.

Values are never shown by default. Revealing one is a deliberate action, and it's logged every time — see Approvals and requests for how a reveal gets approved and the security page for how the project treats sensitive data generally.

Most access grants are either a plain yes or a plain no. One level is narrower: a service account can be allowed to create and update secrets in a folder, but reveal only the ones it created itself — never the folder's other secrets. That's meant for a machine that manages its own credentials (a host storing its own local-admin password, say) without being handed read access to everything else nearby.

An admin sets this from the folder's access screen (admin app, Folders → the folder → Sharing), Advanced view: clicking a subject's Reveal cell cycles blank, allow, own, deny, blank, so own sits between the plain allow and deny it narrows. A secret's own page shows which principal created it, so an admin checking this grant can see at a glance whose secrets a given own-reveal subject can actually reveal.

Top-level folders​

By default, anyone signed in can create a top-level folder, with New shared folder in the staff app's sidebar or the top-level choice in the New Folder dialog. A personal token can too, which is how an agent makes one (see Using the MCP).

  • It belongs to its creator. If a token made it, it belongs to the token's user. The owner manages it and shares it with the people who need it.
  • Everyone signed in sees it listed, by name and owner. The contents stay with its owners and site admins until an owner shares it.
  • Tokens see it once it's shared. Until then it isn't in a token's folder list.
  • Agents can't share. No token can change a folder's sharing, not even its owner's. A person does that in the staff app.

A service account or workload can't make a top-level folder, because it has no user to own it.

To limit this, a site admin turns on Restrict top-level folders to admins in the admin console's Settings. It's off by default. While it's on, only site admins and root can create a top-level folder, in the staff app or through a token whose owner is one. Anyone else is refused, and the message names the setting. Subfolders aren't affected.

Moving a folder to the top level follows the same setting, so a subfolder can't be promoted around it. The staff app offers that move to site admins only, and a token can't make it at all. Reordering the folders already at the top level is separate, and needs an admin.