Certificate and request fields

Field-by-field reference for the objects the API returns. The API reference has the authoritative schemas; this page explains what the fields are for.

Certificate summary

Returned by GET /v1/certificates.

Field	Type	Null	Notes
id	uuid		NextPKI’s identifier. Use this for all API calls
fingerprint_sha256	string		SHA-256 of the certificate. The real identity - see below
common_name	string	yes	Legacy field. Empty on many S/MIME and CA certificates
issuer_dn	string		Full issuer DN. Often long; truncate for display
serial_number	string		Unique per issuer only, not globally
not_before	date-time		Start of validity
not_after	date-time		End of validity
cert_type	enum		See enumerations
key_algorithm	enum		Includes hybrid and post-quantum values
is_revoked	boolean
trust_status	enum		Verdict of chain validation
last_seen_at	date-time		Most underrated field - see below
org_id	uuid	yes	Organisation assignment, if any

Certificate detail

GET /v1/certificates/{id} adds:

Field	Type	Null	Notes
subject_dn	string		Full subject DN
signature_algorithm	string		e.g. ecdsa-with-SHA256. sha1WithRSAEncryption is a finding
san_dns	string[]		What clients actually check
san_email	string[]		Populated on S/MIME certificates
first_seen_at	date-time		When NextPKI first observed it

Renewal request

Returned by GET /v1/requests and GET /v1/requests/{id}.

Field	Type	Null	Notes
id	uuid
previous_cert_id	uuid	yes	The certificate being replaced
new_cert_id	uuid	yes	Populated once issuance succeeds
via_connector_id	uuid	yes	Which CA account was used
state	enum		See the state machine
state_reason	string	yes	Failure detail when state is failed
attempts	integer		Worker attempts so far
org_id	uuid	yes
scheduled_at	date-time		When the worker should next act
created_at	date-time
updated_at	date-time		Last state change

Note there is no certificate PEM here. new_cert_id tells you issuance succeeded; retrieving the certificate is not possible through v1.

Three fields worth dwelling on

fingerprint_sha256, not serial_number

Serial numbers are unique per issuer. Two CAs can legitimately issue the same serial, so keying your own storage on serial will collide on a mixed-CA estate - which is precisely the estate NextPKI exists to manage. Key on id internally and on fingerprint_sha256 when comparing against certificates you observed yourself.

last_seen_at

This is what separates an inventory from a list of expiry dates. not_after answers “when does this expire” - arithmetic. last_seen_at answers “is anything still serving it”, which is the question that decides what you do:

not_after	last_seen_at	Meaning
soon	recent	Renew it. In service and about to expire
soon	weeks ago	Clean it up. Nothing serves it; renewing wastes money
far off	never by a sensor	Issued for your domain but not deployed in your network. Investigate

Filtering an expiry report on last_seen_at is the single change that turns it from noise into a work queue.

common_name is nullable, san_dns is what matters

Clients have validated against SAN, not Common Name, for years. A certificate with only a CN and no SAN is rejected by every current browser.

So do not build display or matching logic on common_name alone:

def display_name(cert):
    return cert.get("common_name") or (cert.get("san_dns") or [None])[0] or cert["id"]

Nullable fields, collected

Handle these as absent, not as empty strings: common_name, org_id, previous_cert_id, new_cert_id, via_connector_id, state_reason.

A statically typed client that maps these to non-optional types will silently turn null into "" or the zero UUID, and you will eventually chase a bug where a renewal appears to reference the nil certificate. See client libraries.