# Credential

a secret Tonoman holds for a tenant — a token, a login, a published calendar address — always handled by reference, never shown.

**Has:** one tenant · a reference that names it · the sealed value · which master key sealed it · when it was written and last replaced. A tenant has many, one per reference. A connection's account names one; so does an agent's channel.

## How it is held

- The master key comes from outside the database, and the registry refuses to start without it.
- A connection, an agent's channel and a skill's settings each name a credential; none of them holds one.
- A reference names either a credential the registry holds or one the deployment mounts, and the two are never confused.

## Who may use it

- A worker asks for a credential by naming its agent and can never name a tenant.
- Reading, writing or forgetting a credential needs the platform's own token, and a deployment without one does not offer it at all.
- Only the worker is ever handed a credential value, and only one it is about to use.
- A credential is never shown on a screen, returned to a browser, or written to a log; only its reference is.
- A credential travels in the body of a request, never in its address.

## Replacing and forgetting

- A Google or Outlook login is renewed here and stored back; a caller receives only a short-lived token. Plaud is the exception: the worker holds and renews that login itself.
- A credential pasted into the Hub is used once before it is kept, so a wrong one fails at set-up.
  - e.g. a spent bot token → "that bot token did not validate", nothing stored.
- Forgetting a credential twice is not an error; the answer says whether there was one.
- Removing a connection leaves its credential; forgetting it is a separate act ([CONN-DISCONNECT-KEEPS-SECRET](https://tonoman.com/docs/connection#conn-disconnect-keeps-secret)).
- If the master key is lost every credential is gone and every customer reconnects; it is kept away from the database and its backups.
- "Connection" is retired as a word: the Hub says credentials (its Credentials screen, "Credentials it can use" on an agent), a credential carries the label, the alias, shared-or-personal and the status, and an instance's binding says who uses it ([SKILL-BINDING-PER-TOOL](https://tonoman.com/docs/skill#skill-binding-per-tool)). `!credentials` is the command, `!connections` kept as an alias. (The `connection.md` rules describe the same rows by their older name.)
- Wherever a credential is listed it says which skills use it, on which agents; one nothing uses reads "Not used by any skill". Until bindings ([SKILL-BINDING-PER-TOOL](https://tonoman.com/docs/skill#skill-binding-per-tool)), a skill uses a credential when its agent is granted it and the skill needs its kind; with them, it is the instance bound to it.

## In the Hub

- A Credentials screen lists everything held for the tenant: its label, its kind, whose it is (the tenant's or a person's), what uses it ([CRED-USED-BY](https://tonoman.com/docs/credential#cred-used-by)), and when it was added. Never a value.
- Only an owner, an admin or an operator opens the Credentials screen.
- A screen that needs to know whether a credential is set is told only that one exists.

## In dev

- The dev stack holds its own logins under its own key; no production credential is copied into it.