Re: [PATCH docs 3/9] user management: document the API token policy

["Shannon Sterz" <s.sterz@proxmox.com>]

On Wed Sep 23, 2026 at 10:59 PM CEST, Thomas Lamprecht wrote:
> Describe the new datacenter token-policy option next to the general
> API token section, so admins who need to fulfill compliance
> requirements find the enforcement options in one place. The option
> reference itself is generated from the datacenter.cfg schema.
>
> Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
> ---
>  pveum.adoc | 34 ++++++++++++++++++++++++++++++++++
>  1 file changed, 34 insertions(+)
>
> diff --git a/pveum.adoc b/pveum.adoc
> index d089cb6..0849657 100644
> --- a/pveum.adoc
> +++ b/pveum.adoc
> @@ -115,6 +115,40 @@ To use an API token, set the HTTP header 'Authorization' to the displayed value
>  of the form `PVEAPIToken=USER@REALM!TOKENID=UUID` when making API requests, or
>  refer to your API client's documentation.
>
> +[[pveum_token_policy]]
> +Token Policy
> +~~~~~~~~~~~~
> +
> +The optional `token-policy` datacenter option sets cluster-wide rules for
> +creating and updating API tokens, as compliance standards like PCI DSS,
> +SOC 2, or ISO 27001 often require, most notably a limited credential
> +lifetime. The policy can require an expiration date for new tokens, limit
> +how far in the future the expiration date can be set, forbid changing the
> +expiration date of existing tokens, and require privilege separation.
> +
> +Changing the policy requires `Sys.Modify` on `/`, like any other datacenter
> +option. Configure it in the web interface under *Datacenter -> Options ->
> +API Token Policy*, or on the command line:
> +
> +[source,bash]
> +----
> +pvesh set /cluster/options --token-policy max-lifetime=7776000
> +----
> +
> +`max-lifetime` is set in seconds (7776000 above is 90 days), while the web
> +interface takes days. It counts from when the expiration date is set, that
> +is on token creation or when an update changes it, and implies
> +`require-expiry`, as a token without an expiration date would exceed any
> +maximum lifetime.
> +
> +The policy only applies when a token is created or updated, and only to
> +values that actually change. Existing tokens stay valid even if they do not
> +conform to a policy configured later, and unrelated updates of such tokens
> +keep working. Extending the expiration date within the limit stays possible
> +too, unless `disallow-expiry-changes` is set, which forbids any change of
> +the expiration date after creation; such tokens can still be deleted and
> +recreated.
> +

imo a warning here that the policy will not be enforced by nodes that
aren't updated in a cluster would be nice here. while this this is maybe
obvious, this is a compliance feature. so being transparent about such
limitations could safe costly a back-and-forth with auditors.

>  [[pveum_resource_pools]]
>  Resource Pools
>  --------------