Wenn dein Produkt fachlich mit einer Vertragslaufzeit von einem Jahr arbeitet, die CA aber nur kürzere Zertifikatslaufzeiten ausstellt, kannst du 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 dein eigenes Commerce- oder Billing-Modell darüber hinausgeht, kannst du 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

Lege 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
}
'

Speichere neben der API-Antwort direkt deinen internen Steuerdatensatz. Die providerseitige Vertragsgrenze kommt jetzt aus dem API, zusätzlicher kaufmännischer Kontext bei Bedarf weiter aus deinem 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

Nimm die von validation.dns_records gelieferten Records und lege sie in DNS an. Danach pollst du 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 speicherst du 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, starte 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 nutzt du nur dann, wenn du für geeignete Multi-Year-Bestellungen bewusst eine kürzere Ersatzlaufzeit anfordern willst
• nutze contract_valid_until aus dem API als Vertragsgrenze und ergänze nur dann eine eigene kaufmännische Grenze, wenn dein Geschäftsmodell das zusätzlich verlangt

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

Wenn das Entscheidungsmodell reissue-now liefert, löst du 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
}
'

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

Schritt 5: DCV-Token effizient aktualisieren

Verlasse dich nicht darauf, dass der alte DCV-Token weiterhin gültig ist. Lies den neuen Record aus response.reissue.validation.dns_records und aktualisiere 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, lädst du das neue Zertifikat über dieselbe Zertifikats-id herunter und schreibst deinen 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 speicherst du mindestens:

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

Bei einem normalen Re-Issue musst du 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, legst du keine weitere Folge-Ausstellung auf derselben Bestellung an. Stattdessen erzeugst du eine neue Bestellung und markierst 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 behandelst du 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

• behandle Re-Issue-Jobs idempotent, zum Beispiel pro Vertrag und Zielgeneration
• generiere den nächsten CSR vor dem Re-Issue-Fenster, damit die Folge-Ausstellung nicht auf Schlüsselerzeugung wartet
• halte den DNS-TTL kurz, damit geänderte DCV-Token schnell greifen
• plane einen kleinen Puffer zwischen Bestellung und erwartetem Deployment ein
• verwende 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 kannst du bei Bedarf weiter intern ergänzen.