TLS-Laufzeit mit Re-Issue-Zyklus maximieren

Wenn Ihr Produkt fachlich mit einer Vertragslaufzeit von einem Jahr arbeitet, die CA aber nur kürzere Zertifikatslaufzeiten ausstellt, können Sie den Ablauf mit dem aktuellen regfish API jetzt deutlich sauberer automatisieren.

Wichtig ist die neue Trennung der Modelle: Folge-Ausstellungen innerhalb derselben Bestellung laufen per POST /tls/certificate/{certificate_id}/reissue auf derselben Zertifikats-id. Der Übergang in die nächste Vertragsperiode läuft dagegen als neue Bestellung über POST /tls/certificate mit renewal_of_certificate_id.

Das API liefert die providerseitige Vertragsgrenze jetzt über contract_valid_from und contract_valid_until mit. Falls Ihr eigenes Commerce- oder Billing-Modell darüber hinausgeht, können Sie den Ablauf zusätzlich mit eigenen Fachdaten anreichern.

Voraussetzungen

ein API-Key mit Zugriff auf TLS- und DNS-Endpunkte
die aktuelle Zertifikatsantwort inklusive contract_valid_until
optional ein intern gespeichertes kaufmännisches Vertragsende, falls es von der providerseitigen Vertragsgrenze abweicht
eine aktive Zertifikats-id, die aktuell produktiv genutzt wird
ein Job oder Scheduler, der täglich oder mehrfach täglich prüfen kann
ein frischer CSR für jede Folge-Ausstellung
eine Zone, die über regfish DNS verwaltet wird

Schritt 1: Initial mit maximaler CA-Validity bestellen

Legen Sie die erste Ausstellung direkt mit der maximalen öffentlich dokumentierten validity_days an. Im aktuellen OpenAPI-Stand sind das 199 Tage.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "sku": "RapidSSL",
  "common_name": "www.example.com",
  "dns_names": ["api.example.com"],
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token",
  "validity_days": 199
}
'

Speichern Sie neben der API-Antwort direkt Ihren internen Steuerdatensatz. Die providerseitige Vertragsgrenze kommt jetzt aus dem API, zusätzlicher kaufmännischer Kontext bei Bedarf weiter aus Ihrem eigenen System.

{
  "contract_valid_from": "2026-03-16T00:00:00Z",
  "contract_valid_until": "2027-03-16T23:59:59Z",
  "active_certificate_id": "7K9QW3M2ZT8HJ",
  "sku": "RapidSSL",
  "common_name": "www.example.com",
  "dns_names": ["api.example.com"],
  "dcv_method": "dns-cname-token"
}

Schritt 2: Erste Ausstellung abschließen und Laufzeit merken

Nehmen Sie die von validation.dns_records gelieferten Records und legen Sie sie in DNS an. Danach pollen Sie die Bestellung, bis valid_until und certificate_pem_available gesetzt sind.

curl --request POST \
  --url 'https://api.regfish.com/dns/rr' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "type": "CNAME",
  "name": "_dnsauth.example.com",
  "data": "0123456789abcdef.dcv.digicert.com.",
  "ttl": 300
}
'

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ' \
  --header 'x-api-key: YOUR_API_KEY'

Aus der fertigen Antwort speichern Sie mindestens:

contract_valid_from
contract_valid_until
valid_from
valid_until
status
certificate_pem_available

Schritt 3: Re-Issue-Fenster berechnen

Der effiziente Ablauf minimiert Überlappung und wartet deshalb bis kurz vor das aktuelle Zertifikatsende. Gleichzeitig darf ein Re-Issue nicht mehr angestoßen werden, wenn die verbleibende providerseitige Vertragslaufzeit praktisch schon aufgebraucht ist.

Ein einfaches Entscheidungsmodell sieht so aus:

reissue_lead_days = 7
safety_days = 2

days_until_expiry = floor((valid_until - now) / 86400)
days_until_contract_end = floor((contract_valid_until - now) / 86400)

if days_until_contract_end <= reissue_lead_days + safety_days:
  action = "renew-next-term"
elif days_until_expiry > reissue_lead_days:
  action = "wait"
else:
  action = "reissue-now"

Wichtig dabei:

re-issue erst kurz vor valid_until, damit keine unnötige Laufzeit verloren geht
wenn die Restvertragslaufzeit praktisch verbraucht ist, starten Sie nicht noch ein Re-Issue, sondern die nächste Verlängerung als neue Bestellung
die Hauptoptimierung passiert weiterhin über den richtigen Auslösezeitpunkt; validity_days im Re-Issue nutzen Sie nur dann, wenn Sie für geeignete Multi-Year-Bestellungen bewusst eine kürzere Ersatzlaufzeit anfordern wollen
nutzen Sie contract_valid_until aus dem API als Vertragsgrenze und ergänzen Sie nur dann eine eigene kaufmännische Grenze, wenn Ihr Geschäftsmodell das zusätzlich verlangt

Schritt 4: Re-Issue auf derselben Bestellung auslösen

Wenn das Entscheidungsmodell reissue-now liefert, lösen Sie das Re-Issue direkt auf der vorhandenen Zertifikats-id aus. Genau hier ist der neue Endpoint deutlich passender als die frühere Modellierung über eine neue Zertifikatsbestellung.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ/reissue' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token",
  "comments": "Scheduled reissue near certificate expiry",
  "validity_days": 90
}
'

Verwenden Sie für dieses Re-Issue vorzugsweise einen neuen Schlüssel und damit einen neuen CSR. validity_days senden Sie nur dann mit, wenn Sie bewusst ein kürzeres Ersatzzertifikat anfordern wollen und die zugrunde liegende Multi-Year-Bestellung das unterstützt.

Schritt 5: DCV-Token effizient aktualisieren

Verlassen Sie sich nicht darauf, dass der alte DCV-Token weiterhin gültig ist. Lesen Sie den neuen Record aus response.reissue.validation.dns_records und aktualisieren Sie den bestehenden _dnsauth-Record bevorzugt per PATCH /dns/rr.

curl --request PATCH \
  --url 'https://api.regfish.com/dns/rr' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "type": "CNAME",
  "name": "_dnsauth.example.com",
  "data": "fedcba9876543210.dcv.digicert.com.",
  "ttl": 300
}
'

Falls der Record noch nicht existiert, fällt der Workflow für diesen Schritt auf POST /dns/rr zurück.

Schritt 6: Neues Zertifikat übernehmen und Steuerzustand fortschreiben

Sobald das Re-Issue ausgestellt ist, laden Sie das neue Zertifikat über dieselbe Zertifikats-id herunter und schreiben Sie Ihren internen Steuerzustand fort.

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ' \
  --header 'x-api-key: YOUR_API_KEY'

curl --request GET \
  --url 'https://api.regfish.com/tls/certificate/7K9QW3M2ZT8HJ/download/pem' \
  --header 'x-api-key: YOUR_API_KEY' \
  --output 'certificate-7K9QW3M2ZT8HJ.pem'

Danach speichern Sie mindestens:

active_certificate_id = 7K9QW3M2ZT8HJ
neues valid_until
reissue.requested_at oder einen eigenen Zeitstempel der letzten Folge-Ausstellung

Bei einem normalen Re-Issue müssen Sie das alte Zertifikat in der Regel nicht widerrufen. Es kann nach erfolgreichem Deployment regulär auslaufen.

Schritt 7: Nächste Vertragsperiode als explizite Verlängerung starten

Wenn das Entscheidungsmodell renew-next-term liefert, legen Sie keine weitere Folge-Ausstellung auf derselben Bestellung an. Stattdessen erzeugen Sie eine neue Bestellung und markieren Sie sie explizit als Verlängerung des bisherigen Zertifikats.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "sku": "RapidSSL",
  "common_name": "www.example.com",
  "dns_names": ["api.example.com"],
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC...NEXT...\n-----END CERTIFICATE REQUEST-----",
  "dcv_method": "dns-cname-token",
  "renewal_of_certificate_id": "7K9QW3M2ZT8HJ",
  "validity_days": 199
}
'

Diese Anfrage erzeugt eine neue Bestellung mit neuer Zertifikats-id. Genau deshalb ist sie kein Re-Issue, sondern der Start des nächsten Vertrags- oder Abrechnungszyklus. Für den weiteren Ablauf behandeln Sie die Antwort wie jede andere neue Bestellung: neuen DCV-Record übernehmen, neuen Auftrag pollen, neues Zertifikat über die neue Zertifikats-id herunterladen und intern die Zuordnung renewed_from_certificate_id -> new_certificate_id speichern.

Wichtig bei Verlängerungen: validity_days bleibt die gekaufte Basislaufzeit. Sobald die Bestellung ausgestellt ist, sind valid_until und, falls vorhanden, renewal_bonus_days die maßgeblichen Felder für die effektiv gutgeschriebene Laufzeit.

Praxishinweise für produktive Abläufe

behandeln Sie Re-Issue-Jobs idempotent, zum Beispiel pro Vertrag und Zielgeneration
generieren Sie den nächsten CSR vor dem Re-Issue-Fenster, damit die Folge-Ausstellung nicht auf Schlüsselerzeugung wartet
halten Sie den DNS-TTL kurz, damit geänderte DCV-Token schnell greifen
planen Sie einen kleinen Puffer zwischen Bestellung und erwartetem Deployment ein
verwenden Sie für den Wechsel in die nächste Vertragsperiode explizit renewal_of_certificate_id, statt blind eine komplett unverbundene Neubestellung zu erzeugen

Ergebnis

Mit dem aktuellen regfish API lässt sich dieser Lifecycle jetzt deutlich sauberer automatisieren: Die erste Ausstellung läuft über create-certificate, spätere Folge-Ausstellungen innerhalb derselben Bestellung über reissue-certificate, und die nächste Vertragsperiode wieder über create-certificate mit renewal_of_certificate_id als explizite Verlängerung. Die providerseitige Vertragsgrenze ist jetzt direkt im API sichtbar; zusätzliche kaufmännische Logik können Sie bei Bedarf weiter intern ergänzen.