pbs_tfa_add
Add a multi-factor authentication entry for a Proxmox Backup Server user. Supports TOTP, U2F, WebAuthn, recovery codes, and Yubico. Preview changes with dry-run before confirming.
Instructions
MUTATION (MEDIUM): add a TFA entry for a user. Dry-run by default.
SECRET-BEARING RESPONSE for type='recovery': confirm=True's result carries
{"recovery": [], ...} — SERVER-GENERATED secret material, shown ONCE and
never retrievable again. It is never written to the audit ledger (the detail= dict below
never includes 'recovery'/'challenge'/'id'). password, if supplied, is UNCONDITIONALLY
redacted identically to pbs_user_create's. For type='totp', the caller supplies the secret
(via totp) — PBS does not generate one server-side for that type. confirm=True executes and
returns a dict; synchronous, no UPID. Needs PROXIMO_PBS_* config.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| totp | No | For type='totp': the totp: URI the caller generated (PBS does not generate this). | |
| value | No | Registration/verification value (e.g. the current TOTP code, or a WebAuthn/U2F challenge response). | |
| userid | Yes | PBS user id to add a TFA entry for, format 'user@realm'. | |
| confirm | No | False (default) returns a dry-run PLAN preview; True executes the mutation. | |
| password | No | The ACTING user's own current password (re-authenticates the change); redacted from all plans/logs/ledger. | |
| tfa_type | Yes | TFA entry type: 'totp', 'u2f', 'webauthn', 'recovery', or 'yubico'. | |
| challenge | No | For u2f: the original challenge string being responded to. | |
| description | No | Optional description to distinguish this entry from the user's others. | |
| proximo_target | No | Which configured Proxmox target to run this call against — a target name from your multi-target config (a specific PVE/PBS/PMG/PDM box). Omit to use the single/default target from the environment; the selection applies only to this call. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |