Quickstart: store the first secret and reference it

The shortest way from “the plugin is installed” to “another plugin works with a reference instead of a password”. Three steps, about ten minutes.

Prerequisites

wkvault, wkcore and wkstorage are installed and enabled. The vault publishes itself through wkcore's registry and stores its entries through wkstorage; both are required.
You are signed in as superuser — the screen is administrators only.
PHP 8.2 or later.

Step 1: decide the key source — before the first entry

Admin → Configuration, section wkvault, setting keysource.

Value	Where the key lives
`salt` (default)	Derived from the instance salt in `data/meta/`. A backup of the data directory therefore contains the key and the encrypted values.
`env`	In an environment variable named in `keysource_ref` — outside the data directory and outside the wiki backup.
`file`	In a key file whose path is in `keysource_ref`; sensibly outside the web root. It must travel with the installation.

Changing this later is safe — every entry carries the fingerprint of the key it was encrypted under, and the screen then offers re-keying. Choosing deliberately now saves you that run.

Step 2: create the entry

Admin → Vault, directly /doku.php?do=admin&page=wkvault. Section Create or replace:

Field	What goes in it
Id	The key references point at. Choose a stable, descriptive one such as `mail-smtp`.
Secret	The value. It is encrypted before it is stored.
Description	For whoever reads the list later. Optional.
Expires on, Rotate every … days	Optional; drives the state shown in the list.

Step 3: reference it from another plugin

Wherever another plugin asks for a password, enter this instead of the value:

vault:mail-smtp

Five reference schemes are available:

Reference	Resolves to
`vault:<id>`	An entry in this vault.
`env:<NAME>`	An environment variable.
`file:<path>`	The contents of a file, under the configured root only.
`enc:<value>`	A value encrypted in place, without a vault entry.
`plain:<value>`	Exactly what is written.

plain: exists so a reference is always unambiguous. Without it a literal password that happened to contain a colon would be read as a scheme.

Check the result

The entry is in the list with state ok. The value itself is visible nowhere — not to you either.
The consuming plugin's configuration holds vault:mail-smtp and no password.
Trigger the function that needs the secret — a test message in wkmail, say. The access record on the vault screen then carries a row with actor, entry, operation and outcome. The record never contains values; that is the point of it.

Next step

wkmail — the first sensible consumer.
wkresource — the endpoint catalogue that carries only the reference, never the value.
wkvault (German) — the package page: every scheme, hand-over rotation, expiry.