Skip to main content
Version: 0.17

Certificates

Overview​

Certificate Lifecycle Management (CLM) tracks public certificates, deployment history, and renewal status alongside your certificate assets. Private keys stay on your hosts or in the system that manages them.

Start with the task you need:

Use the reference below for lifecycle states, custody, history, and retirement.

An executor is any process on your side (a CI job, a cert-manager hook, or a renewal script) that does certificate work and reports it to TokenTimer. The k8s controller observes cert-manager resources and reports public certificate data to inventory. In opt-in provision mode, it also polls for authorized provisioning commands and asks cert-manager to reconcile certificates; these commands use a separate transport from signed agent jobs. See Certificate automation.

Zero private-key custody​

TokenTimer control plane does not store or generate certificate private keys; customer-side agents may generate them locally. The platform stores only public certificate material (fingerprints, serial numbers, issuers, subjects, SANs, validity dates, chains) and external key references. Uploads or API payloads that contain private key material are rejected with HTTP 422 (PRIVATE_KEY_MATERIAL_REJECTED).

  • Public material: PEM certificates, subject, issuer, serial, fingerprint, and expiry metadata.
  • Key references: which host or cluster holds a key, not the key itself and not a path you can open to read it. For agent-managed certificates this is recorded as the certificate's own path on the agent host, because that is the only coordinate the control plane can verify; TokenTimer never sees the key file.
  • Observations: what the worker saw served at a monitored HTTPS endpoint.

For deployment defaults and the CLM switch, see Configuration.

Managed certificate inventory​

Each certificate identity is one exact certificate, keyed by its normalized SHA-256 fingerprint in a workspace. All endpoints, agents and imports observing it share one inventory entry. Details combine linked token fields and retained Notes with separate Observed locations and Certificate management tables. A source keeps its own management history and renewal configuration; lifecycle belongs to the fingerprint.

Lifecycle and status badges​

Lifecycle is active, revoked or decommissioned for the exact fingerprint. Provisioning, expiry and renewal badges describe its current operational state separately.

  • discovered: first seen through observation or import, not yet confirmed active in inventory.
  • provisioning: created by an issue job and awaiting its first certificate. It flips to active when the job succeeds, and stays at provisioning if the job fails.
  • active: tracked without a revoked or decommissioned lifecycle; expiry is shown separately.
  • renewing: a newer instance was observed while the prior one is still valid.
  • expiring: within the configured expiry threshold.
  • expired: past its expiry (notAfter) date.
  • revoked: retired because the certificate was revoked or must no longer be trusted.
  • decommissioned: retired because the certificate was intentionally taken out of service.

You see managed certificate data on enriched cert rows in the Tokens list and on the certificate operations panel in token detail. The Certificates tab of Certificate Management (/certops/certificates) is the inventory view: a paginated, filterable table (status or source) with Set up renewal, Detach, and Change lifecycle actions per row where eligible (see Bringing an existing certificate under automatic renewal). A row whose renewal-setup attempt failed also carries a separate inline Retry link next to its renewal badge (retries that specific setup intent, not the certificate's whole lifecycle). Retired certificates with fresh presence evidence remain visible by default as Revoked · Still observed or Decommissioned · Still observed. The Retired toggle includes other retired entries; Unmanaged only shows observations without an open management period. The Renewals tab lists certificates too, but only the ones with a renewal profile and only in expiry order, so it is a schedule rather than an inventory.

Importing certificates​

Import a public certificate through the existing Import tokens flow (public PEM card when CLM is enabled) or through the CLM API. This path is for certificates you already hold or that are not tied to an endpoint monitor.

  • Public material only: supply a PEM-encoded certificate. Private keys are rejected with HTTP 422 (PRIVATE_KEY_MATERIAL_REJECTED).
  • Idempotent on fingerprint: importing the same certificate again (same SHA-256 fingerprint) returns the existing managed certificate instead of creating a duplicate.
  • Token linkage: a cert-category token is created or updated alongside the managed certificate.

Endpoint monitor bridge​

When CLM is enabled, endpoint SSL monitoring feeds the managed certificate inventory. The worker observes the public certificate served at a monitored HTTPS endpoint or domain, then records that observation into CLM when the monitor has a linked token.

How it works​

  • Token first: the bridge runs only when the monitor has a linked token_id (including auto-created ssl_cert tokens). No orphan managed certificates are created.
  • One inventory entry per fingerprint: several endpoint monitors serving the same certificate share its inventory entry while retaining their own locations and management periods.
  • Independent rotation: when the served certificate changes from A to B, the source moves to B’s identity. A’s lifecycle never transfers to B; historical observations remain available. Removing an endpoint ends its management period and makes presence unknown. Recreating it opens a new period and rejoins the existing fingerprint identity.
  • Observer only: the monitor watches what is deployed and never modifies your endpoints. Deployment and renewal happen through CLM automation (agents, cert-manager, or your own executors), not through monitors.

For certificates without a URL to observe, use import instead. See also Endpoint & SSL monitoring for monitor setup.

Certificate history​

Each observation of a managed certificate at a target is stored as a certificate instance. Instances form a timeline of what was seen, where, and when.

  • Re-observation refreshes: seeing the same fingerprint again updates the existing instance (last seen timestamp, deployment reference).
  • New fingerprint retains history: rotation adds evidence for the replacement identity without deleting the previous certificate or reopening closed management periods.
  • Certificate detail: the grouped CLM detail shows linked token fields, observed subject, issuer, serial and fingerprint. Location and management tables stay beneath Notes; token details do not duplicate these tables. Failed probes, disconnected agents and incomplete scans mean unknown, not confirmed absence.
  • API: list instances via GET .../certificates/{certId}/instances (public observation fields only).

Instance history helps you answer when a certificate rotated, what was previously served, and whether observations are still current.

Renewals and approvals​

Inventory tracks what is deployed; renewing a certificate is a job, not an inventory edit. See Certificate Automation for renewal scheduling, the kill switch, and bulk renew, and Executor jobs for job status transitions (including pending_approval). See Approval gates and Certificate renewal failures for the approval and alerting detail.

What gets written to certPath

An agent-executed renewal deploys the full chain (leaf certificate plus intermediates) to certPath by default, not the leaf alone - a leaf-only certificate is untrusted by any client that does not separately fetch intermediates. If a target needs the leaf and the chain in separate files, configure chainPath instead: see First-time issuance for both.

Requesting a certificate TokenTimer does not track yet is also a job: an issue job, which creates the managed certificate at status provisioning and fills it in from the agent's evidence when the job succeeds. See First-time issuance.

Not every certificate in inventory can be renewed for you​

This is the single most common surprise in CLM, so it is worth stating plainly: appearing in your inventory does not mean TokenTimer can renew it. Inventory answers "what is out there"; renewal requires something on your side that actually holds the private key and can write a new one.

Every managed certificate has a key custody mode, which records where its private key lives:

Key custodyWhere the key livesCan TokenTimer run a renew/deploy/reload/revoke job?
agent-localOn the agent host that discovered itYes
proxy-agent-localOn a proxy host managed by an agentYes
os-store-managedInside Windows CNG, on the agent host (a windows-iis target's certificate store + IIS binding)Yes
cert-manager-managedIn your Kubernetes cluster, owned by cert-managerNo, cert-manager renews it. TokenTimer observes and reports (see CLM with ACME and cert-manager)
appliance-managed, hsm-managed, vault-managedIn an appliance, HSM, or VaultNo, the owning system renews it
not setNowhere TokenTimer knows aboutNo, it was only observed

That last row is the one people hit. A certificate discovered by an endpoint monitor or the domain checker was seen from the outside, over the network. TokenTimer knows its subject, issuer, expiry, and fingerprint, and will alert you before it expires, but it has never had any access to the host serving it and no agent has custody of its key. There is nothing to renew with.

Creating a renew, deploy, reload, or revoke job against such a certificate fails immediately:

{
  "error": "This certificate has no agent-manageable key custody (it was only observed, e.g. via an endpoint or domain monitor) and cannot be assigned an agent-executed renew job",
  "code": "CERTOPS_CERTIFICATE_NOT_AGENT_DEPLOYABLE"
}

Jobs against observed-only certificates are refused at creation (CERTOPS_CERTIFICATE_NOT_AGENT_DEPLOYABLE), so they never become a false renewal-failure alert.

To make an observed certificate renewable, give an agent real custody of it: install the agent on the host that actually serves the certificate. Its filesystem discovery will find the certificate on disk and register it with agent-local custody, at which point renewal jobs work normally. Observation and custody then coexist: the endpoint monitor keeps verifying what is really being served from the outside, which is how you confirm a renewal actually took effect.

Custody makes a certificate eligible for renewal; it does not by itself make it auto-renew. Automatic renewal additionally needs a linked renewal profile, which is derived for you only when TokenTimer issued the certificate. See Renew certificates automatically.

The renewal badge tells you which case you are in​

Because custody and auto-renewal are two different things, every certificate carries a renewal badge computed from the same inputs TokenTimer's renewal scheduler uses. It uses the same profile-completeness check the scheduler admits on, so it cannot show "Auto-renews" for a certificate that would in fact be skipped.

BadgeMeaning
Auto-renewsEligible, configured, and scheduled. Shows the renewal date and the lead time in days
Auto-renewal offEligible and configured, but renewal was switched off on its profile. It will expire. Deliberate rather than broken, so it is not flagged as a fault, but it still needs a manual renewal. See Switching automatic renewal off
No auto-renewalAn agent holds the key but there is no usable renewal profile. It will expire. This is the state to act on
Monitored onlyNo agent custody, so renewal is not possible here. Working as designed
Renewal not applicableRetired, or renewal is owned by another system such as cert-manager
Renewal unknownThe state could not be determined. Treated as a caution, not an all-clear, so a stale or unreachable API cannot render a false reassurance
At CA capacityEligible and due, but waiting on the per-CA in-flight cap (CERTOPS_RENEWAL_PER_CA_CAP). Distinct from a blocked or failed renewal. Clears automatically once earlier renewals for that CA finish
Assigned agent ineligibleRenewal is pinned to a real, non-retired agent that cannot currently claim the job (compatibility block or capability mismatch). The badge sits next to the renewal state, including on a certificate that is not yet profiled

The two grey states and the two that mean "this will expire" are deliberately distinct. "Monitored only" is a certificate you were never going to renew here. "No auto-renewal" is a certificate you probably believe is managed and is not. "Auto-renewal off" is a certificate somebody chose not to renew, which is supported, but the certificate still expires on schedule.

Retiring certificates​

Certificate lifecycle changes and stopping source management preserve audit history; neither permanently deletes the certificate. Use Stop managing in the source’s details to end management, or Change lifecycle to record revocation or decommissioning.

  • Lifecycle action: use POST .../certificate-identities/{identityId}/retire with status, a reason and the expectedFingerprintSha256. Legacy record-based requests also require an identity precondition. Unidentified provisioning records can stop management but cannot be revoked or decommissioned.
  • Independent lifecycle: lifecycle is workspace-wide for the exact fingerprint. Retiring A cannot retire a different active B that shares a historical source or token. Recording revocation does not contact the CA.
  • Preserved data: the managed certificate, all certificate instances, and observation metadata remain queryable for history.
  • No hard delete: a managed-backed certificate cannot be hard-deleted from the token surface. Choose the appropriate lifecycle or source-management action instead.

Retiring also stops expiry and renewal-failure alerts for that certificate. Pending renewal-failure alerts are dropped immediately; pending expiry alerts are dropped once no live sibling remains on the shared token. New ones are not queued, and weekly digests omit a token whose lifecycle is retired. Endpoint-down alerts are unchanged.

Hard purge remains available only for manually created cert tokens that are not backed by a managed certificate record.

Choose revoked to record revocation in CLM. Decommissioning declares that, to your knowledge, the certificate is no longer in use. Fresh TLS or service-binding evidence blocks it. Stored copies or uncertain visibility require explicit acknowledgment and a reason; acknowledgment cannot override confirmed service use. Later observations preserve retirement and show Still observed.

Stop managing closes only the selected source’s management period, without changing certificate lifecycle or deployment evidence. Explicit re-add opens a new period with selected automation settings; rediscovery and late job results cannot reopen the old period. Renewal settings remain source-specific.

API reference​

CLM endpoints are workspace-scoped under /api/v1/workspaces/{id}/certops. When CLM is disabled they return 404. See the API reference for authentication and pagination.

  • GET /certificates - list source records; use grouped=true for one row per fingerprint with server-side filtering and pagination.
  • POST /certificates - register a public certificate (PEM body; rejects private keys with 422).
  • GET /certificates/{certId} - fetch one managed certificate by ID.
  • GET /certificates/{certId}/instances - list observation instances (rotation history).
  • POST /certificate-identities/{identityId}/retire - change exact-fingerprint lifecycle with its precondition, reason and required uncertainty acknowledgment.
  • POST /management-periods/{periodId}/stop - stop managing one source; preserve its history.
  • POST /imports - bulk import public certificates (same validation rules).

Example​

Complete session authentication against your Core API origin first. Use the saved cookie jar to read the workspace inventory:

BASE=https://tokentimer.example.com
WORKSPACE_ID=your-workspace-id
curl -sS -b cookies.txt \
  "$BASE/api/v1/workspaces/$WORKSPACE_ID/certops/certificates?limit=20&offset=0"

Session-authenticated writes also need the paired CSRF token. CertOps machine API tokens are scoped to the executor surface; they do not replace a user session for inventory administration.