Dokumentation DSP API

Einleitung

Auf den folgenden Seiten finden Sie die technische Dokumentation der DSP API.

Es handelt sich um eine RESTful API. Zur Übertragung von Daten wird das JSON-Format verwendet. Die openAPI Spezifikation finden Sie hier. Wir stellen Ihnen unter dieser URL zusätzlich ein Swagger Interface zur Verfügung. Dort können Sie erste Funktionen ohne Programmierarbeiten ausprobieren.

Zielgruppe

Zielgruppe sind Entwickler, die auf Basis der bereitgestellten Informationen eigene Schnittstellen zu unserer API implementieren. Voraussetzung für eine erfolgreiche Implementierung sind Kenntnisse in der Schnittstellenprogrammierung sowie gutes Verständnis der Bereiche Domain, SSL & DNS.

Limits

Um eine unsachgemäße Nutzung unserer Infrastruktur zu verhindern, gibt es für diverse Requests Abfrage-Limits. Wenn das jeweilige Limit erreicht ist, werden entsprechende Fehlermeldungen ausgegeben (HTTP Code 429)

Weiterführende Informationsquellen

Thema	Link
REST	https://de.wikipedia.org/wiki/Representational_State_Transfer
OpenAPI Specification	https://spec.openapis.org/oas/latest.html

Thema

Link

REST

https://de.wikipedia.org/wiki/Representational_State_Transfer

OpenAPI Specification

https://spec.openapis.org/oas/latest.html

Erste Schritte

Allgemeine Hinweise

Alle Befehle sind "case sensitive". Bitte achten Sie auf die korrekte Groß-/Kleinschreibung.

Bitte achten Sie darauf, dass alle Anfragen in UTF-8 erwartet werden.

Voraussetzungen

Um auf die API zugreifen zu können, benötigen Sie einen API Key, den Sie im Kundenportal URL beantragen können.

Verbindungsaufbau

Zum Verbindungsaufbau nutzen Sie bitte den API Key. Der API Key wird im Header übergeben. Hierfür benutzen Sie bitte den Parameter "X-API-Key".

Beispiel Header:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Endpoints

Das System stellt diverse Endpoints bereit. Die Endpoints stellen Funktionen zur Verfügung, um die jeweiligen Objekte abzufragen, zu modifizieren oder zu löschen. Sie finden zu vielen Endpoints Möglichkeiten Konfigurations-Parameter, Produkt-Parameter und eine generelle Beschreibung der verwendeten Keys abzufragen.

account

Der Endpoint "account" stellt Informationen und Funktionen zu Accounts bereit.

Ein Account stellt ein Benutzerkonto zu unserem System dar. Alle Objekte wie z.B. Domain, SSL, etc. referenzieren auf einen Account. Ein Account wird immer einem Kunden zugeordnet. Es besteht auch die Möglichkeit, einem Kunden mehrere Accounts zuzuweisen. In der Regel wird letztere Variante dazu genutzt, um Zugriffsrechte aufzuteilen bzw. eine Berechnung von Dienstleistungen auf unterschiedlichen Verträgen zu ermöglichen.

Note	Bitte beachten Sie, dass die "accountid" nicht mit der Kundennummer identisch ist!

Das Objekt selbst enthält Informationen zum Account wie z.B. die Kundenzuordnung.

Zur Veranschaulichung des Objekts stellen wir hier einige Keys dar:

accountid (Id des Accounts)
name (Name des Kunden)
email (eMail-Adresse des Kunden)
customerid (Kundennummer)

Beispiele

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Sie möchten Ihre accountid herausfinden. Ihre Kundennummer ist 123456.

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/account?customerid=123456'

application

Der Endpoint "application" stellt Informationen und Funktionen zu Anträgen bereit.

Diese API nutzt Anträge, um eine asynchrone Bearbeitung von Aufträgen zu ermöglichen. Nach erfolgreicher Bearbeitung eines asynchronen Auftrags wird ein entsprechendes Objekt in anderen Endpoints wie z.B. Domain, SSL, CSR, etc. erzeugt. Eine direkte Erzeugung von Objekten z.B. im Endpoint SSL über die Methode "POST" ist nur für synchrone Prozesse vorgesehen.

Das Objekt selbst enthält Informationen zu einem Auftrag wie z.B. den Status.

Zur Veranschaulichung des Objekts stellen wir hier einige Keys dar:

applicationid (Id des Antrages)
san (FQDN in nativer Schreibweise, z.B. häuser.de)
sanace (FQDN in ASCII/ACE Schreibweise, z.B. xn--huser-gra.de)

Beispiele

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Beantragung eines Zertifikates mit dem san "www.häuser.de" für den Account mit der accountid "888888"

curl --request POST --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/application' -d '{"object": "ssl", "application_type": "registration", "accountid": "888888", "product_type": "letsencrypt_standard", "san": "www.häuser.de", "sanace": "www.xn--huser-gra.de"}'

Note

Es ist nicht notwendig, sowohl die native Form "www.häuser.de" (san) als auch die ascii/ace-Konvertierung "www.xn--huser-gra.de" (sanace) anzugeben. Die Nutzung eines der beiden Parameter "san" bzw "sanace" ist ausreichend. Die API akzeptiert auch eine gemischte Nutzung der Parameter. Es ist nicht notwendig, Ihre vorliegenden Daten in ein bestimmtes Format zu konvertieren.

Abfrage der Informationen zu einem bestehenden Antrag (applicationid = 12345-12345-12345)

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/application?applicationid=12345-12345-12345&object=ssl'

Beantragung eines CSR mit ECC-Schlüssel

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/application' -d '{"accountid": 88888, "application_type": "registration", "object": "ssl", "product_type": "ssl_csr", "key_size": 256, "key_type": "ecc", "contactid_owner": 9055, "sanace": "xn--huser-gra.de", "san": "häuser.de"}'

Note	Es können sowohl "ecc" als auch "rsa" als key_type genutzt werden.

contact

Der Endpunkt "contact" stellt Informationen und Funktionen zu Kontakten bereit.

Innerhalb eines Kontakt-Objekts werden alle relevanten Informationen zum Kontakt hinterlegt. Dies kann folgende Informationen beinhalten: Firma, Adresse, eMail, Telefon, usw. Die benötigten Informationen hängen von den Bedingungen der jeweiligen Registrierungs- bzw. Zertifizierungsstelle ab.

Zur Veranschaulichung des Objekts stellen wir hier einige Keys dar:

name_organisation (Firmenname)
name_lastname (Nachname)
id_vatid (Umsatzsteuer Identifikationsnummer)

Beispiele

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Erstellen eines Kontaktes

curl --request POST --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/contact/ -d {"accountid": 88888, "name_organisation": "Meine Firma", "name_organisation_unit": "Meine Firma Support", "name_firstname": "Tim", "name_lastname": "Muster", "address_street": "Hauptstrasse", "address_street_number": "21", "address_city": "Koeln", "address_state": "Nordrhein-Westfalen", "address_country_code": "DE", "email": "hostmaster@plusserver.com", "phone_number": "0049220310453500"}'

Auflisten aller Kontakte mit dem Nachnamen "Muster"

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/contact/?name_lastname=Muster'

Auflisten aller Kontakte mit dem Firmennamen "Meine Firma"

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/contact/?name_organisation=Meine%20Firma'

Auflistung aller Requirements für die "CSR" Beantragung

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/contact/contact_product_requirements?object=ssl&contact_type=owner&product_type=ssl_csr&extended_information=0'

contact/contact_product_requirements

Der Endpoint "contact/contact_product_requirements" stellt Informationen zu notwendigen Kontaktdaten in Bezug auf ein Produkt bereit.

Zur Bestellung von Produkten kann es nötig sein, zusätzliche Informationen (z.B. Steuernummer, Handelsregisternummer , …) zu einem Kontakt hinterlegen zu müssen. Sie haben hier die Möglichkeit unter Auswahl eines Produkts und Kontakt-Typs, die entsprechenden Informationen abzufragen. Hierbei können Sie auch erweiterte Informationen zu den erlaubten Zeichen anzeigen lassen.

Beispiele

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Auflistung aller Requirements für den Owner Kontakt einer ".de" Domain

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/contact/contact_product_requirements?object=domain&contact_type=owner&product_type=.de&extended_information=0'

Auflistung aller Requirements für den Owner Kontakt eines "CSR"

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/contact/contact_product_requirements?object=ssl&contact_type=owner&product_type=ssl_csr&extended_information=0'

domain

Der Endpoint "domain" stellt Informationen und Funktionen zu Domains bereit.

Innerhalb eines Domain-Objekts werden alle relevanten Informationen zur Domain hinterlegt. Dies beinhaltet sowohl Abrechnungsinformationen wie Registrierungsdaten als auch technische Informationen wie z.B. die konfigurierten Nameserver. Aktuell stehen noch nicht alle Eigenschaften einer Domain zur Verfügung. Zurzeit beschränken sich die Informationen auf Basis-Inhalte, welche zur Beantragung von Zertifikaten notwendig sind.

Zur Veranschaulichung des Objekts stellen wir hier einige Keys dar:

date_active (Registrierungsdatum)
date_inactive (Kündigungsdatum)
domain (Domainname in in nativer Schreibweise, z.B. häuser.de)
domainace (Domainname in ASCII/ACE Schreibweise, z.B. xn--huser-gra.de)

Beispiele

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Auflistung aller Domains des Accounts mit der accountid "888888"

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/domain?accountid=888888'

Informationen zur Domain "häuser.de"

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/domain?domain=häuser.de'

redirect

Der Endpoint "redirect" stellt Informationen und Funktionen zu Redirects bereit.

Innerhalb eines Redirect-Objekts werden alle relevanten Informationen zum Redirect hinterlegt. Dies beinhaltet sowohl die Quell- als auch die Ziel-URL, sowie die Art des Redirects.

Zur Veranschaulichung des Objekts stellen wir hier einige Keys dar:

redirectid (Id des Redirects)
fqdn (Quell-URL)
destination (Ziel-URL)
product_type (Produkttyp / Art des Redirects)

Eine detaillierte Auflistung aller Keys finden Sie in der openAPI Spezifikation. Dort sind auch die verfügbaren Methoden des Endpoints dokumentiert. Eine Beschreibung der Keys finden Sie am Endpoint "/redirect/key_description". Eine Beschreibung der möglichen Produkt-Typen finden Sie am Endpoint "/redirect/product_type". Eine Beschreibung der Konfigurations-Möglichkeiten finden Sie am Endpoint "/redirect/configuration_type". Die jeweils gültige WebserverIP / RedirectIP finden Sie am Endpoint "/redirect/webserver_ip". Diese werden Sie für manuelle Konfigurationen benötigen.

Beispiele

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Auflistung aller Redirects des Accounts mit der accountid "888888"

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/redirect?accountid=888888'

Informationen zum Redirect mit der redirectid "12345"

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/redirect?redirectid=12345'

Anlegen eines neuen Redirects

curl --request POST --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/redirect' -d '{"accountid": 12345,"configuration_type": "redirect_only","destination": "https://www.plusserver.com/ueber-uns/plusserver-kontakt","fqdn": "www.häuser.de","fqdnace": "xn--huser-gra.de","product_type": "standard"}'

ssl

Der Endpoint "ssl" stellt Informationen und Funktionen zu SSL-Zertifikaten bereit.

Innerhalb eines SSL-Objekts werden alle relevanten Informationen zum Zertifikat hinterlegt. Dies beinhaltet sowohl Abrechnungsinformationen wie das Bestelldatum als auch technische Informationen wie z.B. die Daten des Keys. Sie haben über diesen Endpoint auch die Möglichkeit, das "autorenew"-Verhalten für bestimmte Zertifikate anzupassen. Sie können "autorenew" aktivieren (1) bzw. deaktivieren (0). Eine Deaktivierung des "autorenew" ist nur beim neusten Zertifikat notwendig.

Note	Bitte beachten Sie, dass wir bei Standard-Requests abgelaufene Zertifikate für Sie herausfiltern. Wenn Sie Informationen abgelaufener Zertifikate benötigen, müssen Sie den Parameter "valid_until" verwenden. Sie können auch Operatoren wie "größer als" oder "kleiner als" verwenden.

Zur Veranschaulichung des Objekts stellen wir hier einige Keys dar:

autorenew (automatische Erneuerung)
applicationid (Nummer des Antrags eines Ihrer Zertifikate)
product_type (Produkttyp)
sslid (Nummer des Zertifikates)
valid_until (Ablaufdatum der Gültigkeit)

Externe Zertifikate

Unter /ssl/external_managed stellen wir Ihnen die Möglichkeit zur Verfügung, externe Zertifikate anderer Anbieter zu übermitteln. Die Übertragung der Zertifikatsdaten erfolgt selbstverständlich verschlüsselt. Der Private-Key des Zertifikats wird verschlüsselt in unserer Datenbank hinterlegt und nur zur Laufzeit bei entsprechenden Berechtigungen entschlüsselt. Sie können uns über diesen Weg Ihre bereits vorhandenen Zertifikate zukommen lassen, damit wir diese bei der Konfiguration Ihrer Dienste verwenden. Selbstverständlich ist dies auch für Ihre eigenen Automatisierungen im Zusammenspiel mit der API möglich. Dadurch entfällt für Sie die Notwendigkeit mehrfache Zertifizierungen bei unterschiedlichen Anbietern vornehmen zu müssen.

Beispiele

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Auflistung aller Zertifikate des Accounts mit der accountid "888888" :

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/ssl?accountid=888888'

Auflistung aller Ihrer Zertifikate, die länger als bis zum 21.03.2023 gültig sind:

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/ssl?valid_until=>20230321'

Deaktivieren des autorenew-Status des Zertifikates mit der sslid 123123:

curl --request PATCH --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/ssl' -d '{"sslid":"123123","autorenew":"0"}'

Workflows

Austausch Zertifikat

In diesem Workflow wollen wir Ihnen Möglichkeiten aufzeigen, Ihre internen Prozesse bzgl. des Austauschs von Zertifikaten zu automatisieren. Unsere Informationen skizzieren einen möglichen Prozess lediglich. Anwendungsfälle und Systeme können sehr unterschiedlich sein. Die Prozesse müssen auf die jeweiligen Gegebenheiten abgestimmt werden.

Die nachfolgenden Beispiele beziehen sich auf das Produkt "letsencrypt_standard".

Initiale Zertifikats-Bestellung

Daten

Folgende Daten müssen vorliegen:

Zur Bestellung benötigen Sie die zu zertifizierenden FQDNs z.B. "test.domain.de", den Namen des Produkts z.B. "letsencrypt_standard' und die ID des Accounts, für den Sie die Bestellung durchführen möchten z.B. "12345".

Verifikation

Über unsere API ist es prinzipiell möglich, für jeden beliebigen FQDN ein Zertifikat zu bestellen. Die Prozesse können sich jedoch unterscheiden. Wir unterscheiden grundsätzlich zwischen zwei verschiedenen Prozessen:

direkte Verifikation
indirekte Verifikation

Eine direkte Verifikation ist in folgendem Fall möglich:

Es werden die Nameserver ns1.plusserver.com, ns2.plusserver.com und ns3.plusserver.com in der Konfiguration der Domain genutzt.
Es liegt keine Hidden-Primary-Konfiguration vor.
Die Domain wurde durch Plusserver bzw. eines der Plusserver-Systeme bestellt.
Die Bestellung des Zertifikats erfolgt in dem Account, dem auch die Domain zugeordnet ist.

Sofern alle Punkte zutreffen, kann unser System den Auftrag ohne weitere Verifikation annehmen. Unser System kann sicherstellen, dass der Antragsteller die Berechtigung zum Erhalt eines Zertifikats hat. Weiterhin kann eine Verifikation gegenüber der Registry Let’s Encrypt über die Plusserver DNS erfolgen.

Sobald einer der o.g. Punkte nicht zutrifft, greift für die jeweils betroffenen SANs der Prozess der indirekten Verifikation.

Eine indirekte Verifikation ist in folgendem Fall notwendig:

Es werden nicht die Nameserver ns1.plusserver.com, ns2.plusserver.com und ns3.plusserver.com in der Konfiguration der Domain genutzt.
Es wird eine Hidden-Primary-Konfiguration verwendet.
Die Domain wurde nicht durch Plusserver bzw. eines der Plusserver-Systeme bestellt.
Die Bestellung des Zertifikats erfolgt nicht in dem Account, dem auch die Domain zugeordnet ist.

Sofern einer der Punkte zutrifft, kann unser System den Auftrag nicht ohne weitere Verifikation annehmen. Dies hat je nach Fall unterschiedliche Gründe:

Um eine automatische Verifikation bei der Zertifizierungsstelle vornehmen zu können, ist der Zugriff auf die jeweils verwendeten DNS notwendig. Dies ist nur gegeben, sofern die DNS von Plusserver verwendet werden. Sollten die betroffenen Domains auf einem anderen Nameserver liegen z.B. "Amazon Cloud", "Google Cloud", eigene Nameserver (z.B. Hidden-Primary), etc. kann die Verifikation über das Setzen eines CNAMEs erfolgen (siehe unten).

Um eine automatische Verifikation bei der Zertifizierungsstelle vornehmen zu können, ist es für uns notwendig, Ihre Zugriffsberechtigung zu prüfen. Sofern die Domains, für die Sie Zertifikate bestellen möchten, über einen anderen Dienstleister bestellt wurden, ist dies für uns nicht möglich. Auch in diesem Fall kann die Verifikation über das Setzen eines CNAMEs erfolgen (siehe unten).

Und auch der letzte Punkt der Liste bezieht sich auf die Prüfung der Zugriffsberechtigung. Bestellen Sie eine Domain für einen Account, dem die Domain nicht zugeordnet ist, muss der zugriffsberechtigte Account eine "Genehmigung" erteilen. Auch dies erfolgt erneut über das Setzen eines CNAMEs (siehe unten).

indirekte Verfikation mit CNAME

Liegt einer der o.g. Fälle vor, wird unser System auf die Antragstellung mit einer Fehlermeldung "403 - verification neccessary" reagieren. Innerhalb der Fehlermeldung erhalten Sie eine Information zu allen betroffenen FQDNs und den von uns erwarteten CNAME-Records. Bitte wenden Sie sich an die jeweiligen Eigentümer bzw. Verwalter der Domain und bitten Sie um das Setzen der Records. Sobald alle Records per DNS verfügbar sind, können Sie den identischen Auftrag erneut senden. Unser System wird Ihren Auftrag bei erfolgreicher Prüfung akzeptieren. Fehlende Records würden in einer neuen Fehlermeldung benannt werden.

Löschen Sie die CNAMEs nach Ausstellung des Zertifikats bitte nicht. Sofern bei Ihren Zertifikaten "autorenew" aktiv ist, werden diese Verifikationen für den Renew-Prozess weiterhin benötigt.

Status des Antrags

Sobald Sie Ihren Auftrag erfolgreich gestellt haben, erhalten Sie von unserem System eine "applicationid". Mit Hilfe der "applicationid" können Sie den Status Ihres Auftrags abfragen. Aufträge mit dem Status "success" wurden erfolgreich bearbeitet. Ein erfolgreich abgeschlossener Antrag enthält eine Referenz auf das erstellte Objekt. In diesem Fall ist eine "sslid" enthalten. Über die Abfrage der ID sind alle Zertifikatsinformationen auslesbar.

Zertifikatsinformationen auslesen und auf dem Server konfigurieren

Sie haben über den Endpoint "ssl" diverse Möglichkeiten, Ihre Zertifikatsinformationen auszulesen. Generell gibt es verschiedene Ansätze, zum gewünschten Ergebnis zu kommen. Wir möchten Ihnen hier zwei Ansätze vorstellen:

Zugriff über "sslid"

Ein Ansatz ist die Nutzung der "sslid". Sie können Zertifikatsinformationen anhand der "sslid" auslesen. Ein möglicher Workflow wäre:

Auslesen und Neustart des Dienstes

Speichern Sie sich die "sslid" aus der initialen Bestellung.
Lesen Sie die Daten des Zertifikats mit der entsprechenden ID aus.
Speichern Sie das Zertifikat, die Intermediate-Kette und den Key in den von Ihrem Dienst (Webserver, Mailserver, etc) benötigten Dateien.
Starten Sie Ihren Dienst neu.

Sofern für das Zertifikat "autorenew" aktiviert ist, kann folgender Prozess für die ständige Aktualisierung genutzt werden:

Neueres Zertifikat finden

Note	Neuere Zertifikate verweisen im Key "sslid_ref_previous" auf das vorhergehende Zertifikat. Sie können diesen Parameter in der Suche verwenden, um Zertifikatsinformationen von neueren Zertifikaten zu finden.

Führen Sie eine Suche über den Key "sslid_ref_previous" mit Hilfe Ihrer zuvor gespeicherten "sslid" durch.
Erhalten Sie kein Suchergebnis, so ist kein neueres Zertifikat verfügbar.
Erhalten Sie ein Suchergebnis, so ist das Ergebnis das neue Zertifikat. Speichern Sie sich die "sslid" des neuen Zertifikats und führen Sie erneut den Prozess Auslesen und Neustart des Dienstes durch.

Mit Hilfe der gespeicherten "sslid" können Sie diesen Prozess wiederholen.

Zugriff über san/sanace

Ein anderer Ansatz ist die Nutzung der SANs des Zertifikats. Sie können Zertifikatsinformationen anhand der Keys "san" bzw "sanace" auslesen. Ein möglicher Workflow wäre:

Auslesen und Neustart des Dienstes

Suchen Sie nach einem Zertifikat, welches alle benötigten SANs enthält. Ihr Suchergebnis kann auch Zertifikate zurückliefern, welche mehr als die von Ihnen in der Suche benannten SANs enthält.
Das Suchergebnis kann mehrere gültige Zertifikate enthalten. Suchen Sie das Zertifikat mit der längsten Laufzeit "valid_until" (Format: YYYYMMDD).
Speichern Sie sich den Wert von "valid_until".
Speichern Sie das Zertifikat, die Intermediate-Kette und den Key in den von Ihrem Dienst (Webserver, Mailserver, etc) benötigten Dateien.
Starten Sie Ihren Dienst neu.

Neueres Zertifikat finden

Suchen Sie nach einem Zertifikat, welches alle benötigten SANs enthält. Ihr Suchergebnis kann auch Zertifikate zurückliefern, welche mehr als die von Ihnen in der Suche benannten SANs enthält.
Das Suchergebnis kann mehrere gültige Zertifikate enthalten. Suchen Sie das Zertifikat mit der längsten Laufzeit "valid_until" (Format: YYYYMMDD).
Ist die Laufzeit des gefundenen Zertifikats größer als das bereits bei Ihnen konfigurierte Zertifikat (gespeicherter Wert von "valid_until"), führen Sie bitte den Prozess Auslesen und Neustart des Dienstes durch.
Ist die Laufzeit des gefundenen Zertifikats identisch (oder kleiner), ist keine Anpassung erforderlich.

Verschiedene Beispiel-Requests des Workflows

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Bestellung eines Zertifikats:

curl --request POST --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/application' -d '{"object": "ssl", "application_type": "registration",  "accountid": "12345", "product_type": "letsencrypt_standard", "san": "test.domain.de"}'

Auslesen der Zertifikatsinformationen anhand der sslid:

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/ssl?sslid=12345'

Auslesen der Zertifikatsinformationen anhand der SANs:

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/ssl?san=test.domain.de'

Suche nach einem "Nachfolge-Zertifikat" für das vorhergehende Zertifikat mit der sslid "12345":

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/ssl?sslid_ref_previous=12345'

Änderung des "autorenew"-Status (deaktivieren):

curl --request PATCH --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/ssl' -d '{"sslid":"12345","autorenew":"0"}'

FAQ

Für die Nutzung der Beispiele wird angenommen, dass Sie eine Header-Datei mit dem Namen "header-file.txt" und folgendem Inhalt angelegt haben:

Content-Type: application/json
X-API-Key: <IHR API-KEY>

Wie finde ich die "accountid" eines Zertifikats heraus?

Beispielhaft stellen wir Ihnen hier die Abfrage für das Zertifkat "www.häuser.de" zur Verfügung:

curl --request POST --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/ssl?san=www.häuser.de'

Ich habe die Fehlermeldung "verification necessary" erhalten, nachdem ich eine Zertifikats-Bestellung aufgegeben habe. Wie muss ich vorgehen?

Bitte folgen Sie in diesem Fall den Anweisungen im "verification"-Objekt. Dort sind ein oder mehrere CNAME-Konfigurationen genannt. Diese Konfigurationen müssen vorgenommen werden, um Ihren Zugriff auf die Domains zu verifizieren. Nachdem Sie die CNAME-Konfigurationen zur Verfügung gestellt haben, stellen Sie den Antrag bitte erneut. Die implementierten Checks werden den Sachverhalt erneut prüfen.

Wie kann ich eine Liste aller Domains meines Accounts erhalten?

Beispielhaft nehmen wir eine Abfrage für den Acccount "888888" vor:

curl --request POST --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/domain?accountid=888888'

Wie kann ich herausfinden ob ich Zugriff auf mehrere Accounts habe?

curl --request GET --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/account?accountname=*'

Wie kann ich mehrere SANs in einem Zertifikat bestellen?

Beispielhaft nehmen wir eine Bestellung für die "accountid" 12345 und den SANs ("san") www.domain.de, test.domain.de und mail.domain.de vor:

curl --request POST --header '@header-file.txt' 'https://api.dsp.plusserver.com/v1.0/application' -d '{"object": "ssl", "application_type": "registration",  "accountid": "12345", "product_type": "letsencrypt_standard", "san": ["www.domain.de", "test.domain.de", "mail.domain.de"]}'

Bei welchem Zertifikat sollte ich das "autorenew" deaktivieren?

Das "autorenew" muss beim neuesten Zertifikat deaktiviert werden. Dieses finden Sie anhand der "valid_until"-Informationen bzw. der höchsten ID. Vorhergehende Zertifikate, bei denen eine Erneuerung bereits stattgefunden hat, müssen nicht mehr berücksichtigt werden.