From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id 8925F1FF0AB for ; Wed, 23 Sep 2026 23:00:41 +0200 (CEST) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 663C42167A; Wed, 23 Sep 2026 23:00:14 +0200 (CEST) From: Thomas Lamprecht To: pve-devel@lists.proxmox.com Subject: [PATCH docs 3/9] user management: document the API token policy Date: Wed, 23 Sep 2026 22:59:52 +0200 Message-ID: <20260923210000.4031318-4-t.lamprecht@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20260923210000.4031318-1-t.lamprecht@proxmox.com> References: <20260923210000.4031318-1-t.lamprecht@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1790197207387 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.555 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) POISEN_SPAM_PILL 0.1 Meta: its spam POISEN_SPAM_PILL_1 0.1 random spam to be learned in bayes POISEN_SPAM_PILL_3 0.1 random spam to be learned in bayes RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: VEOXZXJLLGHQDKMUYLT3ODU5H3YBT7DD X-Message-ID-Hash: VEOXZXJLLGHQDKMUYLT3ODU5H3YBT7DD X-MailFrom: t.lamprecht@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- 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. + [[pveum_resource_pools]] Resource Pools -------------- -- 2.47.3