secretsmgr handbook
Editor sign-in

The cast of characters

Five nouns. That is the entire model.

ThingWhat it is
OrganizationYour team, and a boundary of trust. One organization has one repository, one member list, and one root of trust: a master signature key, kept offline, that vouches for who is on the member list. Two organizations share nothing.
PrincipalA keypair with a name. You are a principal. So is your CI pipeline. The tool treats people and machines identically; the difference is a label, not a mechanism.
VaultA named group of secrets that share an access list. Typically one per environment or per system: prod, staging, billing.
GrantThe record that says "the key to this vault, locked so that only this principal can open it, put there by that principal". Access is the grant, so there is no separate permission list to get out of sync.
SecretA named slot in a vault, holding a value and its version history.

Note what is not on the list: there is no token, no session object, no service account with a password. If you find yourself looking for one, the answer is always "it is a principal, with a keypair".