From 0da13f78e9eb012a5de1683625a07624536f5a11 Mon Sep 17 00:00:00 2001 From: rculpepper Date: Thu, 2 Oct 2025 14:12:36 -0400 Subject: [PATCH 1/3] Add docs for new sys/billing/certificates endpoint --- .../system/billing-pki-certificate-count.mdx | 61 +++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx new file mode 100644 index 0000000000..f97e4c8c9f --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx @@ -0,0 +1,61 @@ +--- +layout: api +page_title: /sys/billing/certificates - HTTP API +description: >- + The `/sys/billing/certificates` endpoint is used to return data about the number of PKI certificates issued by Vault. +--- + +`# /sys/billing/certificates` + +The `/sys/billing/certificates` endpoint is used to return data about the number of PKI certificates issued by Vault. +It returns information for the entire cluster. + +## PKI Certificate Counts + +This endpoint returns the number of PKI certificates issued by Vault in each month of the given time range. +If there are no counts for a given month, an error will be returned for that month. + +| Method | Path | +| :----- | :-------------------------- | +| `GET` | `/sys/billing/certificates` | + +### Request Parameters + +- `start_time` `(string: )` - The first month for which to return certificate counts. +The time must be a timestamp in RFC 3339 format (e.g., `2025-01-01T00:00:00Z` for January 2025). + +- `end_time` `(string: )` - The last month for which to return certificate counts. The `end_time` must not be before the `start_time`. +The time must be a timestamp in RFC 3339 format (e.g., `2025-01-01T00:00:00Z` for January 2025). + +### Sample Payload + +```json +{ + "start_time": "2025-01-01T00:00:00Z", + "end_time": "2025-01-01T00:00:00Z" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + http://127.0.0.1:8200/v1/sys/billing/certificates +``` + +### Sample response + +```json +{ + "months": [ + { + "timestamp": "2025-01-01T00:00:00Z", + "counts": { + "issued_certificates": 123 + } + } + ] +} +``` \ No newline at end of file From b5dcf57327f427d11d834884c2b5bed7fe719435 Mon Sep 17 00:00:00 2001 From: Rachel Culpepper <84159930+rculpepper@users.noreply.github.com> Date: Thu, 9 Oct 2025 17:01:16 -0400 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --- .../system/billing-pki-certificate-count.mdx | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx index f97e4c8c9f..ffe4733142 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx @@ -2,24 +2,23 @@ layout: api page_title: /sys/billing/certificates - HTTP API description: >- - The `/sys/billing/certificates` endpoint is used to return data about the number of PKI certificates issued by Vault. + Use the `/sys/billing/certificates` endpoint to fetch data about the number of PKI certificates issued by Vault. --- `# /sys/billing/certificates` -The `/sys/billing/certificates` endpoint is used to return data about the number of PKI certificates issued by Vault. -It returns information for the entire cluster. +Use the `/sys/billing/certificates` endpoint to fetch data about the +number of PKI certificates issued by Vault. for a cluster. ## PKI Certificate Counts -This endpoint returns the number of PKI certificates issued by Vault in each month of the given time range. -If there are no counts for a given month, an error will be returned for that month. +The Certificate Counts endpoint returns the number of PKI certificates issued by Vault, or an error, for each month of the given time range. | Method | Path | | :----- | :-------------------------- | | `GET` | `/sys/billing/certificates` | -### Request Parameters +### Request parameters - `start_time` `(string: )` - The first month for which to return certificate counts. The time must be a timestamp in RFC 3339 format (e.g., `2025-01-01T00:00:00Z` for January 2025). @@ -27,7 +26,7 @@ The time must be a timestamp in RFC 3339 format (e.g., `2025-01-01T00:00:00Z` fo - `end_time` `(string: )` - The last month for which to return certificate counts. The `end_time` must not be before the `start_time`. The time must be a timestamp in RFC 3339 format (e.g., `2025-01-01T00:00:00Z` for January 2025). -### Sample Payload +### Sample payload ```json { From b421a870255b7d418d05853ef0cc38c29883756b Mon Sep 17 00:00:00 2001 From: rculpepper Date: Tue, 14 Oct 2025 14:12:59 -0400 Subject: [PATCH 3/3] change parameter descriptions --- .../api-docs/system/billing-pki-certificate-count.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx b/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx index ffe4733142..2ffb2f4499 100644 --- a/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx +++ b/content/vault/v1.21.x (rc)/content/api-docs/system/billing-pki-certificate-count.mdx @@ -13,6 +13,7 @@ number of PKI certificates issued by Vault. for a cluster. ## PKI Certificate Counts The Certificate Counts endpoint returns the number of PKI certificates issued by Vault, or an error, for each month of the given time range. +By default, the endpoint returns data for the current billing period. | Method | Path | | :----- | :-------------------------- | @@ -20,11 +21,13 @@ The Certificate Counts endpoint returns the number of PKI certificates issued by ### Request parameters -- `start_time` `(string: )` - The first month for which to return certificate counts. -The time must be a timestamp in RFC 3339 format (e.g., `2025-01-01T00:00:00Z` for January 2025). +- `start_time` `(string: "")` - The year and month indicating the first month of the +query range in format `YYYY-MM`. The `start_time` is required if an `end_time` is provided. -- `end_time` `(string: )` - The last month for which to return certificate counts. The `end_time` must not be before the `start_time`. -The time must be a timestamp in RFC 3339 format (e.g., `2025-01-01T00:00:00Z` for January 2025). + +- `end_time` `(string: "")` - The year and month indicating the last month of the +query range in format `YYYY-MM`. The `end_time` is required if a `start_time` +is provided. ### Sample payload