Skip to main content
Version: 0.10

Certificates

Overview​

Certificate operations (CertOps) adds a managed-certificate layer on top of the certificate tokens you already track in TokenTimer. Cert-category tokens (ssl_cert, tls_cert, code_signing, client_cert) are first-class assets: they appear in the Tokens list, Control Center, and token detail views. CertOps enriches those tokens with key locality, issuer, source, and observed deployment and rotation history.

TokenTimer control plane never stores, receives, or generates private keys; customer-side agents may generate keys locally. The platform stores only public certificate material (fingerprints, serial numbers, issuers, subjects, SANs, validity dates, chains) and external key references. Requests that contain private key material are rejected with HTTP 422.

  • Tokens: existing cert tokens keep working for alerting and expiry tracking.
  • Managed certificates: authoritative lifecycle records linked one-to-one with cert tokens when CertOps is enabled.
  • Public material only: inventory and API responses never include private keys.

Enabling CertOps​

CertOps is off by default on self-hosted installs. Turn it on with the environment variable below, then restart the API and worker processes so the setting is picked up.

CERTOPS_ENABLED=true

When CertOps is disabled, CertOps API endpoints return 404 and inventory enrichments do not appear in the dashboard. When enabled, cert rows in the Tokens list and token detail show managed fields and observation history.

For the full list of environment variables, see the Configuration Reference.

Managed certificate inventory​

A managed certificate is the authoritative lifecycle record for a tracked certificate in a workspace. It is linked one-to-one with a cert-category token so existing alerting, filtering, and token workflows keep working without a separate inventory screen.

Lifecycle status values:

  • discovered: first seen through observation or import, not yet confirmed active.
  • active: currently valid and in use.
  • renewing: a newer instance was observed while the previous one was still valid.
  • expiring: within the workspace alert threshold window.
  • expired: past its not-after date.
  • revoked: explicitly marked as revoked.
  • decommissioned: retired from active tracking.

You see managed certificate data on enriched cert rows in the Tokens list and on the CertOps panel in token detail. There is no separate inventory page in the current release.

Importing a certificate​

Import public certificate material through the existing Import tokens flow (paste or upload a public PEM) or through the CertOps API. Only public certificate data is accepted; payloads that include a private key are rejected with HTTP 422.

  • UI: open Import tokens, choose the public PEM import card when CertOps is enabled, and submit the certificate chain.
  • API: register a single certificate with POST /api/v1/workspaces/:id/certops/certificates or bulk import with POST /api/v1/workspaces/:id/certops/imports.
  • Idempotent: re-importing the same certificate fingerprint updates the existing managed record instead of creating a duplicate.

Use import when you have a certificate file but no HTTPS endpoint monitor to observe it.

Endpoint monitoring bridge​

When you monitor an HTTPS endpoint or domain, the worker observes the public certificate currently served there. If the monitor has a linked token, that observation is recorded into CertOps inventory using a token-first rule: the bridge runs only when a token_id is present, including auto-created ssl_cert tokens.

Each endpoint monitor keeps exactly one managed certificate (stable identity keyed by monitor source and reference). When the served certificate rotates, that single record is updated in place with the new fingerprint, serial, and validity dates, and a new observation instance is appended to history.

  • Observer only: an endpoint monitor watches what is deployed; TokenTimer does not push or deploy certificates to the target.
  • Linked token: the monitor must reference a cert token for CertOps enrichment to run.
  • Rotation: detected when a later check reports different public material at the same monitor.

Certificate history​

Each managed certificate keeps a timeline of observed certificate instances. An instance captures public observation fields at a point in time: when it was seen, subject, issuer, serial number, fingerprint, and source.

  • Re-observing the same fingerprint refreshes the existing instance row (last seen timestamp and status).
  • A new fingerprint at the same monitor appends a new instance row, giving you rotation history under one managed certificate.
  • View instances in token detail or fetch them with GET /api/v1/workspaces/:id/certops/certificates/:certId/instances.

Retiring a certificate​

Removing a tracked certificate is retire-first, not a silent delete. Call POST /api/v1/workspaces/:id/certops/certificates/:certId/retire with status decommissioned (planned removal) or revoked (explicitly revoked).

  • The managed certificate moves to the chosen terminal status.
  • The linked cert token receives a mirrored lifecycle status.
  • The managed certificate row, its instances, and audit trail are preserved for compliance review.
  • A managed-backed certificate cannot be hard-deleted from the token surface; use Retire instead.

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

API reference​

CertOps endpoints are workspace-scoped and available when CertOps is enabled. All paths are under /api/v1/workspaces/:id/certops:

  • GET .../certificates list managed certificates
  • POST .../certificates register a public certificate
  • GET .../certificates/:certId certificate detail
  • GET .../certificates/:certId/instances observation history
  • POST .../certificates/:certId/retire retire a certificate
  • POST .../imports bulk import public certificates

See the API reference for authentication, request bodies, and response shapes.

Example: list certificates in a workspace

curl -s \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-tokentimer.example/api/v1/workspaces/WORKSPACE_ID/certops/certificates"