Documentation | CertSecure

Inventory

The Inventory endpoints return the certificate inventory of each CA together with the counts and distributions (status, expiry, key length, signing algorithm, template) that drive the CertSecure Manager dashboards.

For the corresponding user interface, refer to the Inventory section.

Endpoints

Method	Endpoint	Description
GET	/inventory	List certificates from the inventory.
GET	/inventory/additional-filtering-fields	List the extra filter fields the inventory screen offers.
GET	/inventory/ca_cert_count	Count active certificates per CA.
GET	/inventory/cert_details	Get one certificate record from the inventory.
GET	/inventory/count	Count certificates of one CA by status.
GET	/inventory/count_by_template	Count certificates per template.
GET	/inventory/expirationByDays	Count certificates expiring in 2, 7 and 14 days.
GET	/inventory/expired_last_7_days/count	Count certificates that expired in the last 7 days.
GET	/inventory/expiry_count	Count certificates expiring within 2, 7, 14, 30, 60 and 90 days.
GET	/inventory/global_template_categories	List the standard template categories.
GET	/inventory/inventory_cert_count	Count certificates by state (active, pending, denied).
GET	/inventory/key_length_cert	List active certificates with a given key length.
GET	/inventory/key_length_count	Count active certificates by key type and key length.
GET	/inventory/manual-auto-certificate-count	Count (or list) certificates by auto-enrolled versus manual templates.
GET	/inventory/manual-auto-kpi	Count certificates issued from auto-enrolled versus manual templates.
GET	/inventory/ownership	Look up a certificate owner.
POST	/inventory/ownership	Claim ownership of a certificate.
GET	/inventory/properties	List inventory display columns.
POST	/inventory/properties	Set inventory display columns.
GET	/inventory/revoked_cert_count	Count certificates revoked in the last week.
GET	/inventory/revoked_failed_issued_count	Count revoked, failed and issued certificates by age.
GET	/inventory/self-signed-wildcard	Count self-signed and wildcard active certificates.
GET	/inventory/signing_algorithm_count	Count certificates by signing algorithm.
GET	/inventory/template_categories	List template categories for every CA.
POST	/inventory/template_categories	Move templates between categories.
GET	/inventory/template_details	Get the stored details of one certificate template.
GET	/inventory/templates	List the templates a CA publishes.
GET	/inventory/unknown-certs/count	Count third-party certificates.

GET /inventory

The main certificate listing. Requires the View Inventory user permission; without it the answer is 403. ### Response shape The body is always {data, total}. Supplying both count and page returns one page, and total is the number of certificates matching the filters across every page. Omitting either returns every matching certificate in one response, and total is then just the number of rows returned. Rows are ordered by Certificate Effective Date ascending, which is what keeps paging stable. ### CA scoping is silent, by design Every CA named in ca is dropped from the filter unless the caller is a global admin or the CA belongs to their department. If that leaves no CA at all, the response is {"data": [], "total": 0} with status 200 — not 403. An empty result therefore means either "nothing matches" or "you may not see these CAs", and the two are deliberately indistinguishable. Omit ca, or pass all or global, to mean every CA the caller may see. ### Which store is searched type=expiring reads the expiring-certificate store, except for the 0, 2 and 14 day windows, which are no longer pre-computed and come from the inventory itself. In that mode the day parameter must be present (it may be empty when both start and end are given instead). target=certsecure searches the records of certificates this product issued, rather than the whole discovered estate; those records use different field names, and the signing_algorithm, public_key_algorithm, key_usages and enhanced_key_usages filters do not apply to them. ### Filters Every parameter is optional and the filters combine with AND. A comma-separated filter matches a certificate carrying any of its values, except key_usages, enhanced_key_usages, watchers and tags, which must all be present. Administrator-defined custom fields are filtered with cf_<field name>=value query parameters (case-insensitive substring match; several comma-separated values match any of them). Parameters this endpoint shares with the KPI endpoints (startDate, endDate, cert_type, output, additional) are accepted and have no effect here.

Note: Call this endpoint without a trailing slash (/inventory). The Swagger API lists it as /inventory/.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	Comma-separated CertSecure CA names to include. `all`, `global` or omitting it means every CA the caller may see. Entries the caller is not entitled to are removed silently; see above.
`template`	Query	string	No	Comma-separated certificate template names to include (exact match). Certificates with no template are only returned when neither this nor `categories` is given.
`categories`	Query	string	No	Comma-separated template category names. Expanded to the templates those categories hold for the requested CAs and used in place of the CAs' full template list; if `template` is also given, only templates in both apply. A value naming no category matches nothing.
`status`	Query	string	No	Comma-separated lifecycle states to include (exact match), e.g. `active,revoked`. When given it overrides the state implied by `type`.
`type`	Query	string	No	What to read. `active` (the default), `expired`, `denied`, `failed`, `revoked` and `pending` select certificates in that state, unless `status` is given. `expiring` reads the expiry store and requires `day`, or `start` and `end`. Any other value applies no state filter.
`target`	Query	string	No	Set to `certsecure` (lower case) to search only certificates issued through this product. Any other value, or omitting it, searches the whole estate.
`day`	Query	string	No	Expiry window in days. Must be present when `type=expiring`; it may be empty if `start` and `end` are both supplied. `0`, `2` and `14` are served from the inventory; every other value from the pre-computed expiry store.
`start`	Query	string	No	Lower bound of an expiry window, in days. Only used with `end`, when `type=expiring` and `day` is empty.
`end`	Query	string	No	Upper bound of an expiry window, in days. Only used with `start`, when `type=expiring` and `day` is empty.
`expiration_date_from`	Query	string	No	Earliest certificate expiration date, `YYYY-MM-DD`, inclusive. Cannot be combined with `type=expiring` — that pairing is a 400. A malformed date is a 400; an empty value is ignored.
`expiration_date_to`	Query	string	No	Latest certificate expiration date, `YYYY-MM-DD`, inclusive of the whole day. Same restrictions as `expiration_date_from`.
`effective_date_from`	Query	string	No	Earliest certificate effective (start-of-validity) date, `YYYY-MM-DD`, inclusive. Ignored with `target=certsecure`. A malformed date is a 400; an empty value is ignored.
`effective_date_to`	Query	string	No	Latest certificate effective date, `YYYY-MM-DD`, inclusive of the whole day. Ignored with `target=certsecure`.
`revocation_date_from`	Query	string	No	Earliest revocation date, `YYYY-MM-DD`, inclusive; matches either the revocation date or the effective revocation date. Ignored with `target=certsecure`.
`revocation_date_to`	Query	string	No	Latest revocation date, `YYYY-MM-DD`, inclusive of the whole day. Ignored with `target=certsecure`.
`san`	Query	string	No	Subject alternative name to match (case-insensitive substring).
`keyLength`	Query	string	No	Comma-separated public key sizes in bits to match. With `target=certsecure` every value must be an integer (otherwise 400).
`page`	Query	integer	No	One-based page number. Paginates only when `count` is also given.
`count`	Query	integer	No	Rows per page. Paginates only when `page` is also given.
`common_name`	Query	string	No	Subject common name; case-insensitive substring, comma-separated values match any.
`organization`	Query	string	No	Subject organization; case-insensitive substring, comma-separated values match any.
`organization_unit`	Query	string	No	Subject organizational unit; case-insensitive substring, comma-separated values match any.
`country`	Query	string	No	Subject country code; case-insensitive substring, comma-separated values match any.
`state`	Query	string	No	Subject state or province; case-insensitive substring, comma-separated values match any.
`city`	Query	string	No	Subject locality; case-insensitive substring, comma-separated values match any.
`signing_algorithm`	Query	string	No	Signature algorithm; case-insensitive substring, comma-separated values match any. Not applied with `target=certsecure`.
`public_key_algorithm`	Query	string	No	Public key algorithm; case-insensitive substring, comma-separated values match any. Not applied with `target=certsecure`.
`owner`	Query	string	No	Certificate owner; case-insensitive substring, comma-separated values match any.
`key_usages`	Query	string	No	Comma-separated key usages the certificate must all carry (case-insensitive exact match). Not applied with `target=certsecure`.
`enhanced_key_usages`	Query	string	No	Comma-separated extended key usages the certificate must all carry (case-insensitive exact match). Not applied with `target=certsecure`.
`watchers`	Query	string	No	Comma-separated watcher e-mail addresses that must all be on the certificate (case-insensitive exact match).
`tags`	Query	string	No	Comma-separated tags the certificate must all carry (case-sensitive exact match).

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	The matching certificates as `{data, total}`. One page when both `count` and `page` were supplied, otherwise every match. Also the response when every requested CA was filtered out by entitlement, in which case `data` is empty and `total` is 0. Rows carry the stored certificate fields plus one key per custom field; the fields shown are the common ones.
400	A parameter was malformed or an unsupported combination was requested.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
403	The caller does not hold the View Inventory permission. A CA the caller may not see is filtered out silently instead of producing this.
500	The query failed unexpectedly. The message carries the underlying error text after `Internal Server Error -` .

Example Response

{
  "data": [
    {
      "Serial Number": "4A1B2C3D4E5F",
      "Common Name": "www.example.com",
      "caName": "Issuing CA 1",
      "status": "active",
      "Certificate Template": "WebServer",
      "Certificate Effective Date": "9/17/2026 10:04 AM",
      "Certificate Expiration Date": "9/17/2027 10:04 AM",
      "Key Length": "2048"
    }
  ],
  "total": 1
}

GET /inventory/additional-filtering-fields

Returns the filter fields (identifier, display label and the kind of input control: input, multiselect, dropdown, number or date) that the UI offers in addition to the basic search. source=certsecure returns the shorter list used for certificates issued through CertSecure; any other value, or none, returns the full inventory list.

Request Parameters

Name	Located In	Type	Required	Description
`source`	Query	string	No	Which field list to return. `certsecure` (case-insensitive) selects the shorter list without the signing algorithm, public key algorithm, key usage and effective/revocation date fields; any other value, or omitting it, selects the full `inventory` list. Never rejected.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/additional-filtering-fields" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	The available filter fields.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.

Example Response

[
  {
    "field": "template",
    "label": "Certificate Template",
    "filter": "multiselect"
  },
  {
    "field": "common_name",
    "label": "Common Name",
    "filter": "input"
  },
  {
    "field": "expiration_date",
    "label": "Expiration Date",
    "filter": "date"
  }
]

GET /inventory/ca_cert_count

Returns the number of active certificates for every CA the caller may see (all CAs for a global administrator, otherwise the CAs held by the caller's department). A CA with no cached data reports 0; an empty object is returned when no CA is configured.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/ca_cert_count" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	CA name -> number of active certificates.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

{
  "Issuing CA 1": 1042,
  "Issuing CA 2": 311
}

GET /inventory/cert_details

Returns the inventory record of the certificate with the given serial number under the given CA, without the certificate body and basic-constraints blob. The serial number is tried as given (lower-cased) and then upper-cased. The fields of the record depend on the CA type.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	Yes	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.
`number`	Query	string	Yes	Serial number of the certificate, in hexadecimal as shown in the inventory. Must be present; an unknown or empty value is answered with 404, not 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/cert_details?ca=<ca>&number=<number>" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	The certificate record; fields vary by CA type.
400	A required parameter is missing or the CA is not registered.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
404	No such certificate, or the CA has no inventory record.
500	Unhandled server-side failure.

Example Response

{
  "Serial Number": "4A1B2C3D4E5F",
  "Common Name": "www.example.com",
  "caName": "Issuing CA 1",
  "status": "active",
  "Certificate Template": "WebServer",
  "Certificate Effective Date": "1/1/2026 12:00 AM",
  "Certificate Expiration Date": "12/31/2026 11:59 PM",
  "Key Length": "2048",
  "Signing Algorithm": "sha256RSA"
}

GET /inventory/count

Returns the cached per-status certificate counts for one CA. The set of status keys depends on the CA type (typically active, denied, expired, failed, revoked, and pending for some CAs); a CA with no cached data answers zeros.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	Yes	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/count?ca=<ca>" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Status -> number of certificates.
400	The `ca` parameter is missing or does not name a registered CA.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

{
  "active": 1042,
  "denied": 17,
  "expired": 230,
  "failed": 3,
  "revoked": 41
}

GET /inventory/count_by_template

How many certificates each template has issued, largest first, as a JSON object keyed by template name (or as CSV with output=csv). Each entry carries a CA name and the certificate count. With limit, templates beyond the top N are folded into one Others entry that carries only a count. With none of startDate, endDate, template or additional the answer comes from a per-CA cache that the inventory refresh keeps up to date; using any of them makes the server count live, which is slower on a large inventory. The endpoint answers 200 with {} when nothing matches. Invalid parameter values are reported as 500 with a lower-case error message, not 400.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	Comma-separated CertSecure CA names to count. Omit to count every CA. Names are used as given.
`template`	Query	string	No	Comma-separated template names to count (exact, case-sensitive match). Supplying it makes the server count live instead of using the cache.
`startDate`	Query	string	No	Only count certificates whose effective date is on or after this day, `YYYY-MM-DD`. Supplying it makes the server count live. A malformed date is rejected with a 500.
`endDate`	Query	string	No	Only count certificates whose expiration date is on or before this day, `YYYY-MM-DD`. Supplying it makes the server count live. A malformed date is rejected with a 500.
`additional`	Query	string	No	Comma-separated extra states to count alongside `status`: any of `expired`, `revoked`, `pending` and `failed` (lower case). Other values are ignored. Supplying it makes the server count live.
`limit`	Query	integer	No	Keep only the N templates with the most certificates and fold the rest into `Others`. Must be a positive integer; anything else is rejected with a 500.
`output`	Query	string	No	`csv` returns CSV text instead of JSON. Any other value, or omitting it, returns the JSON object.
`status`	Query	string	No	State to count: `active` (the default), `expired`, `revoked` or `pending`. A live count treats any other value as `active`; the cached count returns `{}` for it.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/count_by_template" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Certificate counts per template. JSON by default; with `output=csv` the same data as CSV text (sent with a `text/html` content type).
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	A parameter was invalid or the count failed. Note the lower-case `error` key, and that bad input is reported as 500 rather than 400.

Example Response

{
  "WebServer": {
    "ca": "Issuing CA 1",
    "count": 46
  },
  "CodeSigning": {
    "ca": "Issuing CA 2",
    "count": 3
  }
}

GET /inventory/expirationByDays

Returns how many certificates are flagged as expiring in 2, 7 and 14 days, for one CA or, when ca is omitted, across all CAs. The CA name is used as given and is not checked against the registered CAs: an unknown name yields zeros.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Optional: omit it for the figures across every CA. Not validated; a name that matches nothing gives zero counts.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/expirationByDays" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Expiry horizon in days -> number of certificates.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

{
  "2": 0,
  "7": 3,
  "14": 5
}

GET /inventory/expired_last_7_days/count

Returns the number of certificates whose status is expired and whose expiry date falls in the last seven days, for one CA or, when ca is omitted or empty, across all CAs. Served from a cache when available, otherwise computed live.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Optional: omit it (or leave it empty) for the count across every CA. Not validated; a name that matches nothing gives 0.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/expired_last_7_days/count" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Number of certificates that expired in the last 7 days.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled failure; `message` carries the exception text.

Example Response

{
  "count": 12
}

GET /inventory/expiry_count

Returns the cached count of certificates due to expire within each horizon. Pass ca=global (case-insensitive) for the totals over every configured CA, or the name of one CA, in which case the caller must be a global administrator or belong to a department that holds that CA (otherwise 403). ca is mandatory.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	Yes	CertSecure name of the Certificate Authority, as returned by `GET /ca`, or the literal `global` for the totals over every configured CA. A name that is not registered, or an empty value, is rejected with 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/expiry_count?ca=<ca>" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Expiry horizon in days -> number of certificates expiring within it.
400	The `ca` parameter is missing or does not name a registered CA.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
403	The caller is neither a global administrator nor in a department that holds the CA.
500	Unhandled server-side failure.

Example Response

{
  "2": 0,
  "7": 3,
  "14": 5,
  "30": 12,
  "60": 20,
  "90": 31
}

GET /inventory/global_template_categories

The category names a template can be filed under, across all CAs: the standard set (SSL/TLS, Code Signing, Server, Client, User, Certification Authority, Other, Uncategorized) followed by any custom category an administrator has created on some CA. Takes no parameters. The first call on a fresh installation stores the standard list.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/global_template_categories" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Category names, in the order they were created.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Reading the categories failed unexpectedly. `details` carries the underlying error text.

Example Response

[
  "SSL/TLS",
  "Code Signing",
  "Server",
  "Client",
  "User",
  "Certification Authority",
  "Other",
  "Uncategorized"
]

GET /inventory/inventory_cert_count

Returns the number of active, pending and denied certificates for one CA, or summed over every CA that has cached counts when ca is omitted. Cached by the inventory refresh cycle.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Optional: when omitted the figures are summed over every configured CA. When supplied it is matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/inventory_cert_count" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Number of certificates in each state.
400	The `ca` value does not name a registered CA.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

{
  "active": 1042,
  "pending": 2,
  "denied": 17
}

GET /inventory/key_length_cert

Returns the active certificates of one CA whose public key has the requested size, as a short projection (serial number, common name, expiry, template, key length and algorithm; the internal record id is not included). At most count rows are returned (20 when count is omitted). An unregistered CA is a 400; a registered CA whose inventory has never been refreshed yields an empty array.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	Yes	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.
`count`	Query	integer	No	Maximum number of certificates to return, a positive integer. Defaults to 20 when omitted; a value that is not an integer, or is below 1, is rejected with 400. A value above 2147483647 is read as 2147483647 (in practice, all of them).
`keyLength`	Query	string	Yes	Public key size in bits, as a string; only certificates with exactly this key length are returned. Must be present; the value itself is not validated.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/key_length_cert?ca=<ca>&keyLength=<keyLength>" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Matching certificates.
400	A required parameter is missing, the CA is not registered, or `count` is not a positive integer.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

[
  {
    "Serial Number": "4A1B2C3D4E5F",
    "Common Name": "www.example.com",
    "Certificate Expiration Date": "12/31/2026 11:59 PM",
    "Certificate Template": "WebServer",
    "Key Length": "2048",
    "Public Key Algorithm": "RSA",
    "caName": "Issuing CA 1",
    "status": "active"
  }
]

GET /inventory/key_length_count

Returns the cached key-length breakdown for one CA: for each public key type (for example RSA, ECDSA) the number of certificates of each key size in bits. The figures are computed by the inventory refresh cycle, so a CA that has not completed a cycle yet answers {"RSA": {}}.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	Yes	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/key_length_count?ca=<ca>" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Key type -> key size (bits, as a string) -> number of certificates.
400	The `ca` parameter is missing or does not name a registered CA.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

{
  "RSA": {
    "2048": 120,
    "4096": 8
  },
  "ECDSA": {
    "256": 14
  }
}

GET /inventory/manual-auto-certificate-count

Every template is classified as auto or manual from its enrollment flags and key usages: a template that requires approval is manual; one with auto-enrollment, or with a client or server authentication usage, is auto; code-signing, certificate-request-agent and user templates, and anything undecided, are manual. What the endpoint returns depends on output: * kpi (the default) — {auto_template_count, manual_template_count, detailed_template_category}: how many certificates were issued from auto and from manual templates, plus, per CA, which templates fall in each class. * csv — the certificates issued from templates of class cert_type, as CSV text. * any other value — the same certificates as a JSON array of rows. Only the states active, expired, revoked and pending are counted; other values in status are dropped. Without ca every configured CA is included. startDate, endDate and additional are accepted for compatibility with the other KPI endpoints and have no effect here. Invalid parameter values are reported as 500 with a details message, not 400.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	Comma-separated CertSecure CA names to include. `all`, `global` or omitting it means every configured CA. A name matching no CA contributes nothing.
`template`	Query	string	No	Comma-separated template names to restrict the classification to (case-insensitive). Omit to consider every template of the CAs.
`status`	Query	string	No	Comma-separated certificate states to count: `active` (the default), `expired`, `revoked`, `pending`.
`target`	Query	string	No	`certsecure` counts certificates issued through this product (the enrollment records) instead of the discovered inventory. Applies to `output=kpi`.
`cert_type`	Query	string	No	Which class of template to list when `output` is not `kpi`: `auto` or `manual`. Any other value means `manual`. Ignored for `output=kpi`.
`output`	Query	string	No	`kpi` (the default) returns the counts; `csv` returns CSV text; any other value returns the certificates as a JSON array.
`startDate`	Query	string	No	Lower bound of the date window.
`endDate`	Query	string	No	Upper bound of the date window.
`additional`	Query	string	No	Comma-separated extra flags, lower-cased before use, interpreted by the KPI and count outputs.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/manual-auto-certificate-count" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	The counts (`output=kpi`), the certificates as a JSON array, or — with `output=csv` — CSV text (sent with a `text/html` content type). Row output has the columns of the CA's report properties when one CA is selected, otherwise `Certification Authority`, `Serial Number`, `Common Name`, `Certificate Template`, `Key Length` and `Status`.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	A parameter was invalid or the query failed. Bad input is reported as 500 rather than 400; `details` carries the reason.

Example Response

{
  "auto_template_count": 120,
  "manual_template_count": 15,
  "detailed_template_category": {
    "Issuing CA 1": {
      "auto": [
        "WebServer"
      ],
      "manual": [
        "CodeSigning"
      ]
    }
  }
}

GET /inventory/manual-auto-kpi

Dashboard KPI: the number of certificates issued from auto templates and from manual templates (see GET /inventory/manual-auto-certificate-count for how templates are classified), summed over the selected CAs. The numbers are the per-CA totals the inventory refresh keeps up to date, so the answer is fast and does not reflect certificates added since the last refresh. Only ca affects the result. Without it every configured CA is summed; a name matching no CA adds zero. The other parameters of GET /inventory/manual-auto-certificate-count (template, status, target, cert_type, output, startDate, endDate, additional) are accepted for compatibility and have no effect. detailed_template_category is always an empty object here. Invalid values for ca (and the ignored filters) are reported as 500 with a details message, not 400.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	Comma-separated CertSecure CA names to sum. `all`, `global` or omitting it means every configured CA.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/manual-auto-kpi" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Totals across the selected CAs.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	A parameter was invalid or the query failed. Bad input is reported as 500 rather than 400; `details` carries the reason.

Example Response

{
  "auto_template_count": 120,
  "manual_template_count": 15,
  "detailed_template_category": {}
}

GET /inventory/ownership

Returns the enrollment record that owns the certificate with this serial number. Any signed-in user may call it; there is no permission check.

Request Parameters

Name	Located In	Type	Required	Description
`serialNum`	Query	string	Yes	Serial number of the certificate whose owner to look up. Matched without regard to case, ignoring surrounding whitespace. A serial that has no owner record answers 404.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/ownership?serialNum=<serialNum>" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	The owner record of the certificate.
400	The `serialNum` query parameter was not supplied.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
404	No owner record exists for this serial number.
500	Unhandled server-side failure.

Example Response

{
  "enrollmentID": 1042,
  "owner": "[email protected]",
  "emailID": [
    "[email protected]"
  ]
}

POST /inventory/ownership

Starts an asynchronous task that takes ownership of an inventory certificate that has no owner and records owner against it. Poll GET /tasks?taskID= with the returned TaskID for the outcome. Only a global administrator (Admin, or the PKIAdmin role) or a Department PKIAdmin whose department holds the certificate's CA may call it. The check runs before the certificate is looked up, so a caller without the right gets 403 whether or not the serial exists. The body must be a JSON object sent with a JSON Content-Type (a body with any other type is treated as missing, 400), serialNum and owner must be non-blank strings and emails, when sent, an array of strings; each wrong field is a 400 that names it. A serial that matches no certificate is a 404.

Request Body (application/json)

Field	Type	Required	Description
`serialNum`	string	Yes	Serial number of the inventory certificate to claim. Matched without regard to case, ignoring surrounding whitespace. Must be a non-blank JSON string (400 otherwise). The certificate must exist (404) and must not be enrolled yet (404 `Owner Found`).
`owner`	string	Yes	E-mail address of the CertSecure user who becomes the owner; it must belong to a registered user. The values `own` and `self` mean the caller. Must be a non-blank JSON string (400 otherwise).
`emails`	array of string	No	Additional e-mail addresses to attach to the certificate record. An array of strings; anything else is a 400. Only addresses of registered users are kept; the others are dropped silently.

Example Request

curl -X POST "https://<certsecure-backend-url>/inventory/ownership" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"serialNum":"4A1B2C3D4E68","owner":"[email protected]","emails":["[email protected]"]}'

Responses

Status Code	Description
200	The claim was accepted and is being processed.
400	The body or one of its fields is unusable, or the owner is not a registered user.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
403	The caller is neither a global administrator nor a Department PKIAdmin for the certificate's CA. Plain text, not JSON.
404	No certificate has this serial number, or it already has an owner.
500	Unhandled server-side failure.

Example Response

{
  "TaskID": "1042"
}

GET /inventory/properties

Returns Active, the columns currently displayed, and Available, every column that can be displayed (the columns common to all selected CAs plus the custom fields). When several CAs are selected only columns common to all of them are listed. Both lists are empty when no CA is configured. The handler reads no properties parameter on GET.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	Comma-separated CertSecure CA names, or `all` / `global`. Optional on `GET`: when omitted or empty every configured CA is used. Required on `POST` (see there). On `GET` a name that matches no CA simply has no effect.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/properties" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Displayed and available columns.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled failure; the message carries the underlying error text.

Example Response

{
  "Active": [
    "Common Name",
    "Serial Number"
  ],
  "Available": [
    "Certificate Expiration Date",
    "Certificate Template",
    "Common Name",
    "Serial Number",
    "Signing Algorithm"
  ]
}

POST /inventory/properties

Replaces the displayed columns of each selected CA with properties. ca is required (400 otherwise) and every name in it must be a registered CA (400 Not a registered CA: <name>); ca=global selects every CA. Names that the CA does not offer (and that are not custom fields) are silently dropped, repeated names are kept once, and Serial Number and Common Name are always added. After that no more than 8 columns may remain for any of the selected CAs, otherwise 400 and no CA is changed. properties must be present but may be empty, which leaves just the two mandatory columns. The change shows in the inventory after the next refresh cycle.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	Yes	Comma-separated CertSecure CA names, or `all` / `global` for every CA. Required, not blank, and each name must be registered.
`properties`	Query	string	Yes	Comma-separated certificate column names to display (not repeated parameters; only the first `properties` parameter is read). The parameter must be present; an empty value is accepted.

Example Request

curl -X POST "https://<certsecure-backend-url>/inventory/properties?ca=<ca>&properties=<properties>" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Columns updated.
400	Missing `properties`, missing or blank `ca`, a value that holds only separators, a CA that is not registered, no CA to apply it to, or too many columns for one of the selected CAs. Nothing is changed.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled failure; the message carries the underlying error text.

Example Response

{
  "Response": "Properties updated. Please refresh inventory or inventory will be updated on next refresh cycle"
}

GET /inventory/revoked_cert_count

Returns the number of certificates revoked in the last week (0-1) for one CA, or the estate-wide figure when ca is omitted. Cached by the inventory refresh cycle; the figure is 0 when nothing is cached yet.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Optional: when omitted the figures are summed over every configured CA. When supplied it is matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/revoked_cert_count" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Revoked-certificate count for the last week.
400	The `ca` value does not name a registered CA.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

{
  "revoked": {
    "0-1": 4
  }
}

GET /inventory/revoked_failed_issued_count

Returns, for the requested CA (or summed over every configured CA when ca is omitted), how many certificates were revoked, failed or were issued in each four-week age bucket: 0-4, 4-8, 8-12 and 12-16 weeks ago. Cached by the inventory refresh cycle.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Optional: when omitted the figures are summed over every configured CA. When supplied it is matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/revoked_failed_issued_count" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Per status, a map of age bucket (weeks) -> number of certificates.
400	The `ca` value does not name a registered CA.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

{
  "revoked": {
    "0-4": 10,
    "4-8": 3,
    "8-12": 17,
    "12-16": 20
  },
  "failed": {
    "0-4": 0,
    "4-8": 0,
    "8-12": 0,
    "12-16": 0
  },
  "issued": {
    "0-4": 177,
    "4-8": 85107,
    "8-12": 126908,
    "12-16": 11957
  }
}

GET /inventory/self-signed-wildcard

Fast path: reads Self Signed Active Count and Wild Card Active Count from each CA document (populated by insert_inventory_count) and sums across the requested CAs. Falls back to a live scan only when one or more CA documents are missing the cached fields (e.g., a fresh CA that has not run a count cycle yet). Without ca all configured CAs are counted.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Optional: omit it to count across every configured CA. Not validated; a name that matches nothing gives zero counts.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/self-signed-wildcard" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Number of self-signed and wildcard active certificates.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled failure; `error` carries the exception text.

Example Response

{
  "self_signed_certs": 4,
  "wild_card_certs": 27
}

GET /inventory/signing_algorithm_count

Returns how many certificates carry each signature algorithm, as cached by the inventory refresh cycle. With ca the figures are for that CA; without it they are summed over every configured CA. An empty object is returned when no CA is configured or the CA has no cached data yet.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Optional: when omitted the figures are summed over every configured CA. When supplied it is matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/signing_algorithm_count" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Signature algorithm name -> number of certificates (empty when nothing is cached).
400	The `ca` value does not name a registered CA.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled server-side failure.

Example Response

{
  "sha256RSA": 1040,
  "sha384RSA": 12
}

GET /inventory/template_categories

One entry per configured CA, each mapping category names to the templates in them. Templates not placed in any category are listed under Uncategorized. Takes no parameters.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/template_categories" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	One object per CA.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	The request failed unexpectedly. `details` carries the underlying error text.

Example Response

[
  {
    "ca": "Issuing CA 1",
    "categories": {
      "SSL/TLS": [
        "WebServer"
      ],
      "Client": [
        "User"
      ],
      "Uncategorized": [
        "CodeSigning"
      ]
    }
  }
]

POST /inventory/template_categories

Files templates under categories for one CA. A template listed under a category is added to it and removed from every other category; listing it under Uncategorized only removes it from its current category. Categories not mentioned are left alone. Every template must exist on the CA and may appear under one category only. Assignments to the seven standard categories (SSL/TLS, Code Signing, Server, Client, User, Certification Authority, Other) are checked against the template's declared key usages before anything is written, and one refused assignment rejects the whole request. Custom categories, Other, Uncategorized and templates with no usage information are not checked. Send validate_only to run the same checks and change nothing. The body must be a JSON object sent with a JSON Content-Type (a body with any other type is treated as missing, 400), and every field is checked for its type before anything is looked up (400).

Request Parameters

Name	Located In	Type	Required	Description
`validate_only`	Query	string	No	Dry run. `1`, `true` and `yes` (case-insensitive) mean the request is validated and nothing is changed; `0`, `false` and `no` mean the real write, as does omitting it. Any other value, including an empty one, is a 400. May also be sent in the JSON body; the request is a dry run when either asks for one, so the body cannot turn a dry run into a write.

Request Body (application/json)

Field	Type	Required	Description
`ca`	string	Yes	CertSecure name of the CA whose categories to change, as returned by `GET /ca`. A non-blank string, otherwise 400; an unknown name is a 404.
`categories`	object	Yes	Category name to the list of template names to place in it. Each template must be one the CA publishes and may appear under only one category. Category names and template names must be non-blank strings and each value an array, otherwise 400.
`validate_only`	boolean or integer or string	No	Optional dry-run flag. `true`, `1`, `"true"`, `"1"` and `"yes"` validate without writing; `false`, `0`, `"false"`, `"0"` and `"no"` write. Any other value, including `null`, is a 400. The request is a dry run when this or the query parameter asks for one.

Example Request

curl -X POST "https://<certsecure-backend-url>/inventory/template_categories" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"ca":"Issuing CA 1","categories":{"SSL/TLS":["WebServer"]},"validate_only":true}'

Responses

Status Code	Description
200	The change was applied, or — with `validate_only` — passed validation without changing anything (`validated` lists each checked template).
400	The body is not a JSON object, is missing `ca` or `categories`, has a field of the wrong type, `validate_only` is not a flag, names a template the CA does not publish, lists a template under several categories, or asks for a move the template's key usages do not allow (nothing is changed). A migration refusal also carries `message` and a `denied` list explaining each refused template.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
404	No CA with that name exists.
500	The request failed unexpectedly. `details` carries the underlying error text.

Example Response

{
  "message": "Template Categories updated successfully"
}

GET /inventory/template_details

Returns the template details cached for the CA in the inventory refresh (key usages, validity, enrollment flags and similar). The set of fields depends on the type of CA. The template name is matched case-insensitively. 500 with Please refresh inventory means the CA has no inventory record yet.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	Yes	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Matched case-insensitively against the registered CAs; a name that is not registered, or an empty value, is rejected with 400.
`template`	Query	string	Yes	Name of one of the CA's certificate templates, as listed in its template inventory. Matched case-insensitively. Must be present; an unknown or empty value is answered with 404, not 400.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/template_details?ca=<ca>&template=<template>" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Details of the template; fields vary by CA type.
400	A required parameter is missing or the CA is not registered.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
404	The CA has no template with that name.
500	The CA has no inventory record yet, or an unhandled failure.

Example Response

{
  "FriendlyName": "Web Server",
  "EnhancedKeyUsages": [
    "Server Authentication (1.3.6.1.5.5.7.3.1)"
  ],
  "KeyUsages": [
    "Digital Signature, Key Encipherment (a0)"
  ]
}

GET /inventory/templates

Template names available for certificate requests. The shape of the answer depends on ca: * ca supplied — a JSON array of that CA's template names. The CA name is matched case-insensitively. The array is empty when the caller's department is not entitled to the CA, or the CA is access-restricted and the caller lacks the Access Restricted CAs permission. * ca omitted — a JSON object mapping each CA the caller may see to its template names (an empty array for a CA whose templates have not been synced yet).

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of one Certificate Authority, as returned by `GET /ca`. Omit it to list the templates of every CA the caller may see.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/templates" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Template names. An array when `ca` was supplied, an object keyed by CA name when it was omitted.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Reading the CA's templates failed unexpectedly.

Example Response

[
  "WebServer",
  "CodeSigning",
  "User"
]

GET /inventory/unknown-certs/count

Returns the number of third-party certificates (enrollment records flagged thirdPartyCert) for one CA or, when ca is omitted or empty, across all CAs. Served from a cache when available, otherwise counted live.

Request Parameters

Name	Located In	Type	Required	Description
`ca`	Query	string	No	CertSecure name of the Certificate Authority, as returned by `GET /ca`. Optional: omit it (or leave it empty) for the count across every CA. Not validated; a name that matches nothing gives 0.
`status`	Query	string	No	Optional. `active` counts only active certificates; `other` counts every certificate that is not active. With this parameter the count is taken live from the same records `GET /enrollment/unknown-certs` lists, never from the cache.

Example Request

curl -X GET "https://<certsecure-backend-url>/inventory/unknown-certs/count" \
  -H "Authorization: Bearer <token>"

Responses

Status Code	Description
200	Number of third-party certificates.
400	`status` was given and is neither `active` nor `other`.
401	Authentication failed. The `Authorization` header is missing, malformed, expired, revoked, or names a session that no longer exists.
500	Unhandled failure; `message` carries the exception text.

Example Response

{
  "count": 9
}

Inventory

GET /inventory

GET /inventory/additional-filtering-fields

GET /inventory/ca_cert_count

GET /inventory/cert_details

GET /inventory/count

GET /inventory/count_by_template

GET /inventory/expirationByDays

GET /inventory/expired_last_7_days/count

GET /inventory/expiry_count

GET /inventory/global_template_categories

GET /inventory/inventory_cert_count

GET /inventory/key_length_cert

GET /inventory/key_length_count

GET /inventory/manual-auto-certificate-count

GET /inventory/manual-auto-kpi

GET /inventory/ownership

POST /inventory/ownership

GET /inventory/properties

POST /inventory/properties

GET /inventory/revoked_cert_count

GET /inventory/revoked_failed_issued_count

GET /inventory/self-signed-wildcard

GET /inventory/signing_algorithm_count

GET /inventory/template_categories

POST /inventory/template_categories

GET /inventory/template_details

GET /inventory/templates

GET /inventory/unknown-certs/count

On this Page: