custodian principal
Create the identity an agent, service or operator uses, capture its one-time token, and revoke it.
A principal is a named identity that reads from or writes to a vault — an agent, a
service, or an operator. You create one principal per thing that needs access, then
grant it exactly what it needs with custodian grant. Be
signed in with an operator token.
custodian principal create
custodian principal create liberty-agent --kind agent<slug>— the principal's slug, its external identity, fixed once created.--kind <kind>— one ofagent,serviceoroperator(required).
Creating a principal prints its token once. The token is returned by no other route, ever — capture it now:
Created agent principal "liberty-agent".
agent_9f3b2c…
This token is shown once and is not stored — it cannot be retrieved again.The command then prints one line of placement advice for the kind you created. Store an
agent's token wherever that agent reads its secrets from at run time, never baked into
an image; store an operator token now with
custodian login. Either way it is not recoverable.
--json still prints the token exactly once, as part of the object.
custodian principal list
Shows every principal — its slug, kind, how many live grants it holds, and its read, creation and revocation times. It never shows a token: the listing route does not return one.
custodian principal listSLUG KIND LIVE GRANTS LAST READ CREATED REVOKED
liberty-agent agent 2 2026-08-28T08:00:00Z 2026-08-20T09:20:00Z live
old-service service 0 never 2026-07-01T10:00:00Z 2026-08-01T12:00:00Zcustodian principal revoke
Revokes a principal by its slug, after confirming. Once revoked, every grant it holds is treated as absent.
custodian principal revoke liberty-agentAdd the global --yes to skip the confirmation. Revoke is
idempotent: revoking again reports the original time and changes nothing further.
The last live operator of a vault cannot be revoked — the server refuses it so you cannot lock yourself out, and Custodian prints that refusal to you word for word.