Core concepts

Five ideas cover almost everything the API does.

Tenant

A tenant is a customer account and the hard isolation boundary. Every row in the database is scoped to a tenant and enforced at the database level, not in application code - a query cannot accidentally reach across tenants. Your API token belongs to exactly one tenant, and its prefix names it.

Tenants are pinned to a region (eu or us). Data does not move between them.

Organisation

Organisations are a tree inside a tenant, for companies that need to separate subsidiaries, sites or teams without separate accounts. Certificates can be assigned to an organisation, and most list endpoints accept an org_id filter.

A tenant always has at least a root organisation. If you do not care about this split, ignore it - leaving org_id unset works fine.

Certificate

A certificate is identified by its SHA-256 fingerprint, not by serial number. Two CAs can issue the same serial; a fingerprint collision is a different problem entirely. This means the same certificate found by three different sources is one row, not three.

Certificates carry the usual X.509 metadata plus how NextPKI sees them: trust_status, whether it is revoked, and when it was last observed.

Observation

An observation records where and when a certificate was seen. One certificate usually has several: the sensor found it on 10.20.4.10:443, a Certificate Transparency log logged its issuance, and your CA account lists it.

This is the part most inventory tools get wrong. not_after tells you when a certificate expires; observations tell you whether anything still serves it. A certificate with no recent observation is a candidate for cleanup, not renewal.

Renewal

A renewal is a state machine, not a request/response call. States:

pending_approval → approved → csr_generated → submitted → issued → deployed

failed and cancelled are terminal, as is deployed. Transitions are enforced by the database, so an invalid jump is rejected rather than silently applied.

Two things follow from this. First, POST /v1/certificates/{id}/renew returns immediately with a renewal in pending_approval - it does not return a certificate. Second, a human with the approver role has to approve it before any CA is contacted, because issuance costs money. Poll GET /v1/requests/{id} to follow progress.

Certificates flagged for auto-renewal skip the manual create step: a scheduler opens the renewal itself inside a 30-day window before expiry. Approval is still required.