Enumerations

These are the enumerated values the API uses today. Treat every one as an open set: new values are added without a version bump, so handle the unknown case instead of crashing on it. This is the single most common way clients break against NextPKI.

STATUS_LABELS = {"trusted": "Trusted", "self_signed": "Self-signed"}
label = STATUS_LABELS.get(cert["trust_status"], cert["trust_status"])  # never KeyError

cert_type

What the certificate is for. S/MIME is a first-class type, not an afterthought - the S/MIME Baseline Requirements define four distinct validation profiles and they behave differently.

Value	Meaning
tls_server	Server authentication - the common case
tls_client	Client authentication
tls_mutual	Both, typical for service-to-service mTLS
smime_mailbox	S/MIME, mailbox-validated
smime_org	S/MIME, organization-validated
smime_sponsor	S/MIME, sponsor-validated
smime_individual	S/MIME, individual-validated
code_signing	Code signing
document_signing	Document signing
ca	A CA certificate - root or intermediate
unknown	Could not be classified from the certificate’s extensions

trust_status

The result of chain validation, not a property of the certificate itself. A certificate can be perfectly well-formed and still be untrusted because an intermediate was not served.

Value	Meaning
trusted	Chain validated against a public trust store
untrusted	Chain did not validate - often a missing intermediate
self_signed	Subject equals issuer; common on appliances and printers
expired	Past not_after
revoked	Revoked according to CRL or OCSP
unknown	Not yet validated

Note that expired and revoked appear both here and as booleans/timestamps elsewhere (not_after, is_revoked). trust_status is the summarised verdict; the individual fields are the evidence.

key_algorithm

The hybrid and post-quantum values exist because the data model was built to be algorithm-agile - ML-DSA becomes mandatory reading for US National Security Systems in January 2027, and a schema that cannot express a hybrid chain has to be rebuilt at that point.

Value	Notes
rsa	key_size_bits carries the modulus size
ecdsa	key_size_bits carries the curve size, e.g. 256 for P-256
ed25519
ml-dsa	FIPS 204, the ECDSA/RSA successor
hybrid:ecdsa+ml-dsa	Hybrid signature chain
hybrid:rsa+ml-dsa	Hybrid signature chain
slh-dsa	FIPS 205
falcon
unknown

smime_profile

Only meaningful when cert_type is one of the smime_* values.

Value	Notes
legacy	Being phased out under the S/MIME BRs
multipurpose	Maximum 825 days
strict	Maximum 825 days

Renewal state

See the renewal state machine for what moves a renewal between these and what each failure means.

Value	Terminal
pending_approval	no
approved	no
csr_generated	no
submitted	no
issued	no
deployed	yes
failed	yes
cancelled	yes

Observation source_type

Where a certificate was seen. One certificate usually carries several observations from different sources - that fusion is the point.

Value	Meaning
sensor	Found by a discovery sensor in your network
ct_log	Seen in a Certificate Transparency log
connector	Listed in one of your CA accounts
cloud_aws_acm	AWS Certificate Manager
cloud_azure_kv	Azure Key Vault
cloud_gcp_cm	Google Cloud Certificate Manager
cloud_cloudflare	Cloudflare
ad_cs	Microsoft AD CS
manual_upload	Uploaded by a person
domain_probe	Found by probing a common name on a verified domain

Not all of these are implemented yet - see discovery sources for what actually reports today.

Alert alert_type and severity

alert_type	Trigger
expiry_30d, expiry_14d, expiry_7d, expiry_1d	Expiry thresholds
expired	Already past not_after
drift_detected	What is served differs from what is expected
untrusted_chain	Chain validation failed
sct_missing	No Signed Certificate Timestamp
ocsp_failed, crl_failed	Revocation check failed
weak_algorithm	Weak key or signature algorithm, e.g. RSA-1024 or SHA-1
unauthorized_issuance	A certificate appeared that you did not order
anomaly_detected	Unusual renewal volume from a connector

severity is info, warning or critical.

unauthorized_issuance is worth understanding: it fires when Certificate Transparency shows a certificate for one of your verified domains that NextPKI did not order. That is either shadow IT or mis-issuance, and both are worth a phone call.

Sensor status and scan_profile

status	Meaning
pending	Registered, no report received yet
active	Reporting normally
stale	Was active, has stopped reporting
revoked	Identity revoked; reports rejected

scan_profile is conservative (16 concurrent connections, the default), standard (64) or aggressive (256).

Membership role

Role	Can
owner	Everything, including billing and tenant settings
admin	Manage members, connectors, sensors, domains
operator	Create renewals, manage discovery
approver	Approve renewals - the role that authorises spending
viewer	Read only

See roles and permissions.

Domain verification_state and source

verification_state is pending, verified, failed or revoked. Only verified domains are watched. source records how the domain arrived: manual, csv or registrar_api.