Wiki-Quellcode von API-Key
Zuletzt geändert von MACH formsolutions am 08.04.2026
Zeige letzte Bearbeiter
| author | version | line-number | content |
|---|---|---|---|
| 1 | (% class="box infomessage" %) | ||
| 2 | ((( | ||
| 3 | Die Anleitung zum Erstellen eines CMS-Keys finden Sie im Artikel [[CMS-Key erstellen>>https://wiki.machproforms.de/wiki/admindoku/view/Main/01_Systemadministration/03_Installation/03_Abschliessend/02_Datenbank/01_CMS/]] | ||
| 4 | ))) | ||
| 5 | |||
| 6 | == API-Keys für die Authentifizierung == | ||
| 7 | |||
| 8 | [[image:@ServerAdministrationHauptmenüpunkt.jpg||alt="Ansicht des Hauptmenüpunkts „Server-Administration“" data-xwiki-image-style-alignment="end" height="71" width="300"]]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>>https://wiki.machproforms.de/wiki/docwiki/view/Main/03_Hauptnavigationsleiste/]] "Einstellungen/Server-Administration/API-Keys" generiert werden. | ||
| 9 | |||
| 10 | >{{icon name="far fa-info-circle" size="3"/}} //**Hinweis:**// | ||
| 11 | >Diese Funktion steht nur Server-Administratoren zur Verfügung. | ||
| 12 | |||
| 13 | == API-Keys == | ||
| 14 | |||
| 15 | 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. | ||
| 16 | |||
| 17 | === Filter in der API-Keys-Übersicht === | ||
| 18 | |||
| 19 | Über die Filter in der API-Keys-Übersicht kann nach einem/mehreren API-Keys gesucht werden. Folgende Filtermöglichkeiten stehen hierzu zur Verfügung: | ||
| 20 | |||
| 21 | * **Kundennummer (12345678-0000)** | ||
| 22 | * **API-Key** | ||
| 23 | * **Zertifiziert** | ||
| 24 | * **Remote-IP** | ||
| 25 | * **Gültig von** | ||
| 26 | * **Gültig bis** | ||
| 27 | * **Beschreibung** | ||
| 28 | |||
| 29 | === API-Key anlegen [[image:@ApiKeyNeueHinzufügen.jpg||alt="Schaltfläche „Neuer API-Key anlegen“"]] === | ||
| 30 | |||
| 31 | 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. Die Maske enthält die folgenden Felder: | ||
| 32 | |||
| 33 | * **API-Key** | ||
| 34 | Hier wird ein API-Key generiert. | ||
| 35 | Da dieser Wert vom System vergeben wird, ist das Feld schreibgeschützt. | ||
| 36 | * **Kundennummer** | ||
| 37 | Kundennummer im Format 12345678-0000 | ||
| 38 | * **Erstellt** | ||
| 39 | Erstellungsdatum und Datum, ab dem der API-Key gültig ist. | ||
| 40 | Da dieser Wert vom System vergeben wird, ist das Feld schreibgeschützt. | ||
| 41 | * **Gültig bis** | ||
| 42 | Datum, ab dem das Zertifikat nicht mehr gültig ist. Muss mindestens drei Tage nach dem Erstellungsdatum liegen. | ||
| 43 | * **Remote-IP** | ||
| 44 | * **Beschreibung **(interne Notizen) | ||
| 45 | * **Zertifikatsdatei** | ||
| 46 | Es sind Formate nach dem Standard X.509 zugelassen. | ||
| 47 | |||
| 48 | Es ist außerdem verpflichtend, dem API-Key vor dem Speichern eine der unten aufgeführten Berechtigungen zuzuweisen. | ||
| 49 | |||
| 50 | * **SecurePostData** | ||
| 51 | Mit diesem Recht kann der API-Key für die Authentifizierung zur Nutzung der [[SecurePostData-Schnittstelle>>https://wiki.form-solutions.de/wiki/admindoku/view/Main/03_Steuerungsprozess/02_Vorbef%C3%BCllung/02_SecurePostdata/]] verwendet werden. Es wird empfohlen, pro Mandant genau einen API-Key mit diesem Recht zu versehen, um eine Eindeutigkeit des verwendeten Schlüssels zu gewährleisten. | ||
| 52 | * **Unbegrenzt** | ||
| 53 | Mit diesem Recht kann der API-Key für alle vorgesehenen Schnittstellen von MACH formsolutions verwendet werden. | ||
| 54 | |||
| 55 | 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. | ||
| 56 | |||
| 57 | === API-Key bearbeiten [[image:@ApiKeyBearbeiten.jpg||alt="Schaltfläche „API-Key bearbeiten“"]] === | ||
| 58 | |||
| 59 | 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. | ||
| 60 | |||
| 61 | === API-Key löschen [[image:@ApiKeyLöschen.jpg||alt="Schaltfläche „API-Key löschen“"]] === | ||
| 62 | |||
| 63 | 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. | ||
| 64 | |||
| 65 | === Mögliche Fehlerquellen === | ||
| 66 | |||
| 67 | ==== Standardbenutzer nicht vorhanden ==== | ||
| 68 | |||
| 69 | 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//. |