API-Key

API-Keys für die Authentifizierung

Um die von MACH formsolutions bereitgestellten APIs verwenden zu können, muss für jeden Mandanten ein API-Key zur Authentifizierung in der Server-Konfiguration hinterlegt werden. Die Keys können unter der Hauptnavigationsleiste "Einstellungen/Server-Administration/API-Keys" generiert werden.

  Hinweis:
Diese Funktion steht nur Server-Administratoren zur Verfügung.

API-Keys

Unter dem Menüpunkt „API-Keys“ gelangt man in die Verwaltung der API-Keys. Hier können neue sowie bereits angelegte API-Keys verwaltet werden.

Filter in der API-Keys-Übersicht

Über die Filter in der API-Keys-Übersicht kann nach einem/mehreren API-Keys gesucht werden. Folgende Filtermöglichkeiten stehen hierzu zur Verfügung:

• Kundennummer (12345678-0000)
• API-Key
• Zertifiziert
• Remote-IP
• Gültig von
• Gültig bis
• Beschreibung

Neuer API-Key anlegen

Neue API-Keys können über die Schaltfläche „Hinzufügen“ in der API-Key-Übersicht angelegt werden. Daraufhin öffnet sich die Eingabemaske „API-Key anlegen“, in der die Daten zum API-Key hinterlegt werden können. Folgende Stammdaten müssen angegeben werden:

• API-Key
  Hier wird ein API-Key generiert. Da dieser Wert vom System vergeben wird, ist das Feld schreibgeschützt.
• Kundennummer
  Kundennummer im Format 12345678-0000
• Erstellt
  Erstellungsdatum und Datum, ab dem der API-Key gültig ist. Da dieser Wert vom System vergeben wird, ist das Feld schreibgeschützt.
• Gültig bis
  Datum, ab dem das Zertifikat nicht mehr gültig ist. Muss mindestens drei Tage nach dem Erstellungsdatum liegen.
• Remote-IP
• Beschreibung (interne Notizen)
• Zertifikatsdatei
  Es sind Formate nach dem Standard X.509 zugelassen.

Es ist außerdem verpflichtend dem API-Key vor dem Speichern eine der unten aufgeführten Berechtigungen zuzuweisen.

• SecurePostData
  Mit diesem Recht kann der API-Key für die Authentifizierung zur Nutzung der SecurePostData-Schnittstelle verwendet werden. Es wird empfohlen pro Mandant lediglich einen API-Key mit diesem Recht zu versehen, um eine Eindeutigkeit des verwendeten Schlüssels zu gewährleisten.
• Unbegrenzt
  Mit diesem Recht kann der API-Key für alle vorgesehenen Schnittstellen von MACH formsolutions verwendet werden.

Nach der Eingabe aller erforderlichen Daten kann der API-Key über die Schaltfläche „Speichern“ gespeichert werden. Der Ersteller wird daraufhin wieder in die „API-Key-Übersicht“ weitergeleitet in der ein neuer Eintrag erstellt wurde.

API-Key bearbeiten

Müssen die Daten zu einem API-Key geändert werden, so kann dies ein Benutzer, der das entsprechende Recht hat. Hierzu steht die Schaltfläche „Bearbeiten“ in der API-Key-Übersicht direkt am entsprechenden API-Key zur Verfügung. Nach dem Öffnen gelangt man direkt in die Eingabemaske „API-Key bearbeiten“, in der die Daten zum API-Key hinterlegt sind. Nach der Eingabe der geänderten Daten und dem Hochladen eines gültigen Zertifikats muss über die Schaltfläche „Speichern“ der API-Key gespeichert werden.

API-Key löschen

Muss ein API-Key gelöscht werden, kann das ein Benutzer, mit dem entsprechenden Recht, in der API-Key-Übersicht. Hierzu steht neben jedem API-Key die Schaltfläche „Löschen“ zur Verfügung.

Mögliche Fehlerquellen

Standardbenutzer nicht vorhanden

Für die Benutzung der API ist es notwendig, dass unter der Kundennummer (Mandantennummer) der Benutzer {Mandantennummer}-0000 vorhanden ist. Sollte dies nicht der Fall sein, so kommt es z.B. bei der Benutzung der Search-API zu einer UserNotFoundException.