hashicorp · gsantos-hc · Nov 5, 2025
@@ -23,6 +23,12 @@ Evaluation licenses have a 1-day grace period until the license expires. Once
 the evaluation license expires, Vault seals and cannot unseal until you apply
 a valid license.
 
+## PKI-only licenses
+
+PKI-only licenses restrict the secrets engines available on a cluster to Vault's
+built-in PKI secrets engine.
+Review the documentation on <a href="./license/pki">certificates-based entitlements</a>
+for additional information.
 
 ## How licensing works
 

@@ -0,0 +1,78 @@
+---
+layout: docs
+page_title: PKI-only clusters
+description: Technical overview of Vault licensing on PKI-only clusters
+---
+
+# PKI-only clusters
+
+Vault Enterprise 1.21 introduced the ability for customers to license a cluster based on the number of certificates issued through Vault's built-in PKI secrets engine. Customers choosing this option must deploy a cluster that is dedicated to PKI and operating in PKI-only mode.
+
+## Certificate counting
+
+Vault Enterprise clusters running v1.21 and later maintain a count of every certificate issued across all mounts of the built-in PKI secrets engine.
+
+Vault does not deduplicate certificate counts. For example, if you request two certificates with the same Common Name (CN) and Subject Alternative Names (SANs), Vault counts them as two separate certificates.
+
+### Retrieve certificate counts
+
+To retrieve the current certificate usage counts, query the [`sys/billing/certificates`](../../api-docs/system/billing/certificates) endpoint.
+
+#### Sample CLI command and response
+
+<CodeBlockConfig>
+
+```shell-session
+$ vault read -format=json sys/billing/certificates \
+    start_time=2025-10 end_time=2025-11
+{
+  "request_id": "1014dfdc-25f5-9157-ecd2-6991de363831",
+  "lease_id": "",
+  "lease_duration": 0,
+  "renewable": false,
+  "data": {
+    "months": [
+      {
+        "counts": {
+          "issued_certificates": 0
+        },
+        "error": "certificate counts not found for 2025-10",
+        "timestamp": "2025-10"
+      },
+      {
+        "counts": {
+          "issued_certificates": 2
+        },
+        "timestamp": "2025-11"
+      }
+    ]
+  },
+  "warnings": null,
+  "mount_type": "system"
+}
+```
+
+</CodeBlockConfig>
+
+## PKI-only mode
+
+Vault Enterprise clusters entitled on the basis of certificates operate in PKI-only mode. A special flag in the license key automatically activates this mode.
+
+When running in PKI-only mode, the cluster's behavior changes in the following ways:
+
+1. **Restricted Mounts:** The cluster rejects all API requests to any mount of a secret engine other than the built-in PKI secrets engine. This restriction does not affect any authentication or system API paths.
+2. **Client Counting:** The cluster hides the Client Usage dashboard in the Vault UI. Note that the cluster will continue to count clients, but that metric is irrelevant for license utilization purposes on PKI-only clusters.
+
+## Considerations
+
+### Count persistence and data loss
+
+Vault aggregates and persists certificate counts approximately every two minutes. If a cluster node terminates before persisting its in-memory counts, Vault may lose the counts of certificates issued during that interval.
+
+Additionally, Vault attributes certificate issuance counts to the day when those counts were persisted to storage. Certificates issued at the very end of a day, month, or year may be counted on the following day, month, or year.
+
+### Attribution
+
+The certificates issued API endpoint provides certificate counts only. It does not provide attribution to namespaces, mounts, roles, or entities.
+
+To attribute certificate issuance, you must correlate the counts with your audit logs.
@@ -371,6 +371,10 @@
         "title": "Change licenses",
         "path": "license/change-license"
       },
+      {
+        "title": "PKI-only licenses",
+        "path": "license/pki"
+      },
       {
         "title": "Anonymized usage reporting",
         "path": "license/product-usage-reporting"