OV-Zertifikat über API bestellen und mit TLS-Organisation abschließen

Dieses Rezept zeigt den staged OV-Flow mit dem aktuellen TLS API. Die technische Bestellung startet über das öffentliche API, aber die Provider-Bestellung wird nicht sofort abgeschickt, wenn Organisationsdaten noch fehlen oder unvollständig sind. In diesem Fall liefert das API action_required=true zusammen mit einer completion_url.

Der entscheidende Unterschied zu einem normalen DV-Flow ist: Die Zertifikats-id existiert bereits auf API-Seite, aber die providerseitige Bestellung muss erst durch das Binden einer nutzbaren TLS-Organisation vervollständigt werden. Mit dem aktuellen API kann das entweder über POST /tls/certificate/{certificate_id}/complete mit öffentlicher org_id oder manuell in der regfish Console über completion_url passieren.

Voraussetzungen

• ein API-Key mit Zugriff auf TLS- und DNS-Endpunkte
• ein gültiger CSR für das OV-Zertifikat
• eine nutzbare TLS-Organisation oder genügend Daten, um eine anzulegen
• DNS-Zugriff für den späteren DCV-Schritt
• optional ein browserbasierter Nutzerfluss für den Console-Fallback

Schritt 1: OV-Produkt identifizieren

Lies zuerst den TLS-Produktkatalog und wähle ein Produkt, das klar Organisationsdaten voraussetzt.

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

Wähle ein Produkt mit mindestens:

• type = OV
• validation_level = ov
• organization_required = true

Für dieses Beispiel wird SecureSite als OV-Produkt verwendet.

Schritt 2: Öffentliche TLS-Organisations-ID auflösen

Für organisationsvalidierte Zertifikate erwartet org_id jetzt die öffentliche TLS-Organisations-ID aus dem regfish TLS API. Diese IDs sehen wie hdl_7K9QW3M2ZT8HJ aus und nicht wie frühere numerische CA-IDs.

Lies zuerst die vorhandenen Organisationen:

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

Wähle eine Organisation mit mindestens:

• id = hdl_...
• status = ready
• usable_for_ordering = true

Falls noch keine nutzbare Organisation existiert, legst du eine an:

curl --request POST \
  --url 'https://api.regfish.com/tls/organization' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "organization": "Example GmbH",
  "first_name": "Ada",
  "last_name": "Admin",
  "address": "Musterstrasse 1",
  "postal_code": "10115",
  "city": "Berlin",
  "country_code": "DE",
  "phone": "+49 30 1234567",
  "email": "admin@example.com"
}
'

Speichere die zurückgegebene öffentliche Organisations-id, zum Beispiel:

• org_id = hdl_7K9QW3M2ZT8HJ

Schritt 3: OV-Bestellung per API anlegen

Um den staged Flow gezielt zu demonstrieren, legst du die Bestellung zunächst ohne org_id an. Dadurch erzeugt das API zuerst die lokale TLS-Ressource und signalisiert anschließend, dass die providerseitige Bestellung noch fertiggestellt werden muss.

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "sku": "SecureSite",
  "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
}
'

Für eine staged OV-Bestellung sollte die Antwort typischerweise enthalten:

• id
• status = pending
• action_required = true
• pending_reason = organization_required oder completion_required
• pending_message
• completion_url
• organization_id = null

Ein typischer Anwendungsfluss sieht so aus:

const certificate = data.response;

if (certificate.action_required && certificate.completion_url) {
  window.location.assign(certificate.completion_url);
  return;
}

Speichere vor der Weiterleitung mindestens:

• id
• product
• action_required
• pending_reason
• organization_id
• completion_url

Schritt 4: Staged Order per API mit org_id abschließen

Wenn bereits eine nutzbare öffentliche TLS-Organisations-ID bekannt ist, schließt du die staged Bestellung direkt per API ab:

curl --request POST \
  --url 'https://api.regfish.com/tls/certificate/ABCDEFGHJKM23/complete' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '
{
  "org_id": "hdl_7K9QW3M2ZT8HJ"
}
'

Nach einem erfolgreichen Completion-Call erwartest du mindestens:

• action_required = false
• organization_id = hdl_7K9QW3M2ZT8HJ
• dieselbe Zertifikats-id wie zuvor

Das ist der empfohlene Machine-to-Machine-Pfad, wenn deine Integration bereits weiß, welche nutzbare TLS-Organisation gebunden werden soll.

Schritt 5: Optionaler Fallback über die regfish Console

Wenn deine Anwendung die Organisation nicht selbst auswählen kann, öffnest du exakt die completion_url, die das API zurückgegeben hat. Bei staged Orders führt sie auf die Completion-Route in der Console für dieselbe Zertifikats-ID.

Dort vervollständigt der Nutzer anschließend die fehlenden Business-Daten:

• eine vorhandene bestellfähige Organisation auswählen, oder
• eine neue DigiCert-Organisation anlegen, oder
• den staged Order in der Console mit einem letzten Bestätigungsschritt abschließen

Wichtig ist: Dabei entsteht keine neue Zertifikats-id. Dieselbe Zertifikats-id läuft nach dem Console-Schritt weiter.

Falls der Nutzer noch nicht eingeloggt ist, sollte ihn der Console-Login danach wieder auf die Completion-Route zurückführen.

Schritt 6: Prüfen, dass der staged Zustand beendet ist

Nachdem die Bestellung über einen der beiden Wege abgeschlossen wurde, liest du dasselbe Zertifikat erneut über das API.

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

Jetzt erwartest du mindestens:

• action_required = false
• organization_id = hdl_...
• keine weiter blockierende completion_url
• einen normalen pendenden Bestellstatus
• Validierungsdaten, sobald DCV bereitsteht

Ab hier verhält sich der Ablauf wie eine normale Zertifikatsbestellung auf derselben Zertifikats-id.

Schritt 7: DCV-Record nach dem Abschluss setzen

Sobald die abgeschlossene Bestellung validation.dns_records liefert, setzt du den DNS-Record wie gewohnt.

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

Schritt 8: Bis zur Ausstellung pollen und Zertifikat herunterladen

Danach pollst du dieselbe Zertifikats-id, bis das Zertifikat ausgestellt und zum Download bereit ist.

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

Beobachte dabei insbesondere:

• status
• order_state
• validation
• certificate_pem_available

Sobald das Zertifikat bereitsteht, lädst du es wie gewohnt herunter:

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

Praxishinweise für produktive Abläufe

• übergib org_id nur als öffentliche TLS-Organisations-ID aus /tls/organization, zum Beispiel hdl_7K9QW3M2ZT8HJ
• wenn bereits eine nutzbare Organisation bekannt ist, kannst du dieselbe org_id auch direkt auf POST /tls/certificate mitsenden und so den staged Completion-Schritt komplett überspringen
• nutze dieses staged Muster gezielt für OV- und später EV-artige Produkte, bei denen Business-Daten noch fehlen können
• speichere completion_url und pending_reason, damit Support und Automatisierung erklären können, warum eine Bestellung blockiert ist
• behandle organization_id = null als "noch nicht gebunden" und nicht als numerischen Nullwert
• erzeuge nach dem Console-Abschluss keine Ersatzbestellung, sondern poll dieselbe Zertifikats-id weiter
• leite den Nutzer nur auf die vom API gelieferte completion_url weiter, nicht auf einen hart codierten Console-Pfad
• sobald der staged Zustand aufgehoben ist, behandelst du DCV, Polling und Download genauso wie bei jeder anderen Bestellung

Ergebnis

Dieser Ablauf startet die OV-Bestellung über das API, bindet das gestufte Zertifikat über öffentliche org_id an eine nutzbare TLS-Organisation und führt danach DCV und Ausstellung auf derselben Zertifikats-ID fort. So bleibt die Integration am aktuellen TLS API ausgerichtet, während completion_url weiterhin als manueller Fallback verfügbar bleibt.