Certificates

Overview

Certificates are first-class assets in TokenTimer. Cert-category tokens appear in the Tokens list, the Control Center (the summary view at the top of the dashboard showing expiry counts and certificate operations status), and token detail views alongside your other expiring credentials.

CertOps (certificate operations) is TokenTimer's optional layer for teams that manage certificate renewals themselves. If you only want to be alerted before certificates expire, you do not need CertOps: endpoint SSL monitoring, available on all plans, covers that. CertOps adds a managed inventory and renewal-job tracking on the Pro and Team plans.

CertOps enriches cert-category tokens with key locality (where the private key lives, always on your infrastructure, never in TokenTimer), issuer, source, and observed deployment and rotation history. You get a single inventory tied to the token surfaces you already use, not a separate certificate console.

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. See Certificate automation.

Zero private-key custody

TokenTimer control plane never stores, receives, or generates private keys; customer-side agents may generate keys locally. The platform stores only public certificate material 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.

Plan availability

On TokenTimer Cloud, certificate operations through CertOps are available on the Pro and Team plans. See Plan limits.

• Free: 0 managed certificate slots; CertOps write operations are not available. Public SSL endpoint monitoring (adding HTTPS endpoints and tracking expiry via ssl_cert tokens) is available on all plans.
• Pro: full CertOps inventory, import, and API access with 25 active managed certificate slots.
• Team: same CertOps capabilities with 250 active managed certificate slots.

info

Endpoint SSL monitoring does not require a paid plan. Only CertOps inventory operations are plan-gated.

Managed certificate inventory

Each managed certificate is the authoritative lifecycle record for one certificate identity in a workspace. It links one-to-one with a cert-category token: the token is what you see in lists and alerts; the managed certificate holds CertOps fields and observation history.

Lifecycle statuses

• discovered: first seen, 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 and within its validity window.
• 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.

Managed certificates appear in three places: the enriched Tokens list and token detail CertOps panel, the dedicated Certificates tab of Certificate operations (/certops/certificates) with per-row Set up renewal, Detach, Retry, and Retire actions, and the Renewals tab (/certops/renewals) for upcoming automatic renewals (see Bringing an existing certificate under automatic renewal).

Importing certificates

Import a public certificate through the existing Import tokens flow (public PEM card when CertOps is enabled) or through the CertOps 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.
• 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.
• Quota: each new active managed certificate counts against your plan slot limit (see Plans and limits).

warning

Never paste or upload a private key. TokenTimer cannot store key material and will reject the request.

Endpoint monitor bridge

When CertOps 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 CertOps 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 managed certificate per monitor: each endpoint monitor maps to exactly one managed certificate, keyed by monitor identity.
• Rotation in place: when the served certificate changes at the same URL, the existing managed certificate is updated (new fingerprint, serial, expiry) and the linked token metadata is refreshed for alerts.
• Observer only: the monitor watches what is deployed and never modifies your endpoints. Deployment and renewal happen through CertOps 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 appends: a rotation at the same monitor creates a new instance under the same managed certificate, preserving rotation history.
• Token detail: the CertOps panel on token detail shows deployment history and instance fields such as observed subject, issuer, serial, and fingerprint.
• 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, manual renew vs bulk renew, and job status transitions (including the pending_approval state a job sits in while awaiting sign-off). 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 CertOps, 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 custody	Where the key lives	Can TokenTimer run a renew/deploy/reload/revoke job?
agent-local	On the agent host that discovered it	Yes
proxy-agent-local	On a proxy host managed by an agent	Yes
os-store-managed	Inside Windows CNG, on the agent host (a windows-iis target's certificate store + IIS binding)	Yes
cert-manager-managed	In your Kubernetes cluster, owned by cert-manager	No, cert-manager renews it. TokenTimer observes and reports
appliance-managed, hsm-managed, vault-managed	In an appliance, HSM, or Vault	No, the owning system renews it
not set	Nowhere TokenTimer knows about	No, 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"
}

This is a deliberate fail-fast at creation time. The alternative, which earlier builds did, was worse: the job was accepted, some agent eventually claimed it, discovered it had no key or path to work with, and failed. You got a cert_renewal_failed alert that looked like a broken renewal when in fact the renewal was never possible.

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 cannot show "Auto-renews" for a certificate that would in fact be skipped.

Badge	Meaning
Auto-renews	Eligible, configured, and scheduled. Shows the renewal date and the lead time in days
Auto-renewal off	Eligible 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-renewal	An agent holds the key but there is no usable renewal profile. It will expire. This is the state to act on
Monitored only	No agent custody, so renewal is not possible here. Working as designed
Renewal not applicable	Retired, or renewal is owned by another system
Renewal unknown	The state could not be determined. Treated as a caution, not an all-clear, so a stale response cannot render a false reassurance

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.

Plans and limits

Managed certificate slots are a per-workspace quota on TokenTimer Cloud:

• Free: 0 active managed certificate slots.
• Pro: 25 active managed certificate slots.
• Team: 250 active managed certificate slots.

What counts toward the limit

The limit counts only active managed certificates. Statuses such as discovered, provisioning, active, renewing, expiring, and expired all consume a slot. Retiring a certificate to revoked or decommissioned frees its slot, so retired certificates do not count against your quota.

When you reach the limit, registering or importing a new managed certificate is blocked until you move to a plan with more slots or retire an existing certificate. See Plan limits and Pricing.

info

Endpoint SSL monitoring and ssl_cert tokens are not gated by managed certificate slots. Only CertOps inventory operations (import, API registration, monitor bridge writes) consume slots.

Retiring certificates

Removing a tracked certificate is retire-first, never a silent delete. This preserves audit history and frees your managed certificate slot.

• Retire action: call POST .../certificates/{certId}/retire with reason revoked or decommissioned.
• Status mirror: the linked cert-category token receives a matching lifecycle status.
• Preserved data: the managed certificate, all certificate instances, and observation metadata remain queryable for history.
• Slot freed: revoked and decommissioned certificates no longer count toward your active slot quota.
• No hard delete: a managed-backed certificate cannot be hard-deleted from the token surface. Use retire instead.

Choose revoked when the certificate was revoked or must not be trusted. Choose decommissioned when the certificate was intentionally removed from service but was not necessarily revoked by a CA.

API reference

CertOps endpoints are workspace-scoped under /api/v1/workspaces/{id}/certops. On the Free plan these return a plan-required response (HTTP 402 PLAN_FEATURE_REQUIRED). See the API reference for authentication and pagination.

• GET /certificates — list managed certificates in the workspace (limit, offset).
• 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 /certificates/{certId}/retire — retire with revoked or decommissioned.
• POST /imports — bulk import public certificates (same validation and quota rules).

Example

# List managed certificates (Pro or Team workspace)
curl -s -b cookies.txt \
  'https://tokentimer.ch/api/v1/workspaces/WORKSPACE_ID/certops/certificates?limit=20&offset=0' | jq '.'

# Import a public PEM certificate
curl -s -b cookies.txt -X POST \
  'https://tokentimer.ch/api/v1/workspaces/WORKSPACE_ID/certops/certificates' \
  -H 'Content-Type: application/json' \
  -d '{"pem":"-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"}'