Wiki-Quellcode von API-Key
Version 201.1 von MACH formsolutions am 08.04.2026
Verstecke letzte Bearbeiter
| author | version | line-number | content |
|---|---|---|---|
 |
199.1 | 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 | ))) | ||
| |
197.1 | 5 | |
| |
198.1 | 6 | == API-Keys für die Authentifizierung == |
| |
1.1 | 7 | |
| |
201.1 | 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. |
| |
1.1 | 9 | |
| |
198.1 | 10 | >{{icon name="far fa-info-circle" size="3"/}} //**Hinweis:**// |
| 11 | >Diese Funktion steht nur Server-Administratoren zur Verfügung. | ||
| |
1.1 | 12 | |
| |
198.1 | 13 | == API-Keys == |
| |
1.1 | 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 | |||
| |
198.1 | 17 | === Filter in der API-Keys-Übersicht === |
| |
1.1 | 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 | |||
| |
201.1 | 21 | * **Kundennummer (12345678-0000)** |
| 22 | * **API-Key** | ||
| |
198.1 | 23 | * **Zertifiziert** |
| 24 | * **Remote-IP** | ||
| 25 | * **Gültig von** | ||
| 26 | * **Gültig bis** | ||
| 27 | * **Beschreibung** | ||
| |
1.1 | 28 | |
| |
198.1 | 29 | === Neuer API-Key anlegen [[image:@ApiKeyNeueHinzufügen.jpg||alt="Schaltfläche „Neuer API-Key anlegen“"]] === |
| |
1.1 | 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. Folgende Stammdaten müssen angegeben werden: | ||
| 32 | |||
| |
198.1 | 33 | * **API-Key** |
| |
201.1 | 34 | Hier wird ein API-Key generiert. Da dieser Wert vom System vergeben wird, ist das Feld schreibgeschützt. |
| |
198.1 | 35 | * **Kundennummer** |
| |
201.1 | 36 | Kundennummer im Format 12345678-0000 |
| |
198.1 | 37 | * **Erstellt** |
| |
201.1 | 38 | Erstellungsdatum und Datum, ab dem der API-Key gültig ist. Da dieser Wert vom System vergeben wird, ist das Feld schreibgeschützt. |
| |
198.1 | 39 | * **Gültig bis** |
| |
201.1 | 40 | Datum, ab dem das Zertifikat nicht mehr gültig ist. Muss mindestens drei Tage nach dem Erstellungsdatum liegen. |
| |
198.1 | 41 | * **Remote-IP** |
| |
201.1 | 42 | * **Beschreibung **(interne Notizen) |
| |
198.1 | 43 | * **Zertifikatsdatei** |
| |
201.1 | 44 | Es sind Formate nach dem Standard X.509 zugelassen. |
| |
1.1 | 45 | |
| |
198.1 | 46 | [[image:@ApiKeyAnlegen_Stammdaten.jpg||alt="Ansicht der Eingabemaske ~"Neuer API-Key anlegen~" - Stammdaten"]] |
| |
1.1 | 47 | |
| 48 | Es ist außerdem verpflichtend dem API-Key vor dem Speichern eine der unten aufgeführten Berechtigungen zuzuweisen. | ||
| 49 | |||
| |
198.1 | 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 lediglich einen API-Key mit diesem Recht zu versehen, um eine Eindeutigkeit des verwendeten Schlüssels zu gewährleisten. | ||
| 52 | * **Unbegrenzt** | ||
| |
200.1 | 53 | Mit diesem Recht kann der API-Key für alle vorgesehenen Schnittstellen von MACH formsolutions verwendet werden. |
| |
1.1 | 54 | |
| |
198.1 | 55 | [[image:@ApiKeyAnlegen_Berechtigungen.jpg||alt="Ansicht der Eingabemaske ~"Neuer API-Key anlegen~" - Berechtigungen"]] |
| |
1.1 | 56 | |
| 57 | 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. | ||
| 58 | |||
| |
198.1 | 59 | === API-Key bearbeiten [[image:@ApiKeyBearbeiten.jpg||alt="Schaltfläche „API-Key bearbeiten“"]] === |
| |
1.1 | 60 | |
| 61 | 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. | ||
| 62 | |||
| |
198.1 | 63 | === API-Key löschen [[image:@ApiKeyLöschen.jpg||alt="Schaltfläche „API-Key löschen“"]] === |
| |
1.1 | 64 | |
| 65 | 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. | ||
| 66 | |||
| |
198.1 | 67 | === Mögliche Fehlerquellen === |
| |
192.1 | 68 | |
| |
198.1 | 69 | ==== Standardbenutzer nicht vorhanden ==== |
| |
192.1 | 70 | |
| |
198.1 | 71 | 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//. |