> For the complete documentation index, see [llms.txt](https://wiki.lucysecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.lucysecurity.com/lucy-wiki-de/anwendungsreferenz/einstellungen/allgemeine-systemeinstellungen/api-whitelist.md). # API-Whitelist Einführung Die Lucy-API arbeitet als RESTful-Webdienst.\ Daher können alle API-Anfragen in beliebiger Reihenfolge ausgeführt werden, ohne von der Abfolge abhängig zu sein. {% hint style="info" %} Navigieren Sie zu **Einstellungen** -> **Allgemeine Systemeinstellungen** -> **API-Whitelist** {% endhint %} Hier müssen Sie die entfernten IP-Adressen angeben, die mit der API kommunizieren dürfen, um einen kontrollierten und sicheren Zugriff auf den Dienst zu gewährleisten. ### Anforderungen * Der Dienst verwendet ausschließlich JSON als Datenaustauschformat. Alle Antworten der API werden in JSON bereitgestellt, und es wird erwartet, dass die meisten Anforderungsparameter ebenfalls in JSON übermittelt werden. * Jede an die API gesendete Anfrage muss einen "Content-Type"-Header enthalten, der auf "application/json" gesetzt ist, um die ordnungsgemäße Verarbeitung und Interpretation der Anfragedaten sicherzustellen. * Alle Anfragen müssen strikt über das HTTPS-Protokoll erfolgen. Alle an die API gesendeten Anfragen mit einfachem HTTP werden vom Server abgelehnt. ### Authentifizierung Die Lucy-API verwendet JWT (JSON Web Tokens) zur Authentifizierung. Um Vorgänge zu starten, muss zunächst durch Senden einer Authentifizierungsanfrage ein Token angefordert werden. Dieser erste Schritt ist entscheidend, bevor Sie mit weiteren Anfragen fortfahren. Nachfolgend finden Sie Details zur Authentifizierungsanfrage: * **Erhalt des Tokens**: Senden Sie eine Authentifizierungsanfrage an die Lucy-API. Die genauen Details dieser Anfrage, einschließlich des Endpunkts und der erforderlichen Anmeldedaten (typischerweise ein Benutzername und ein Passwort), sind in der API-Dokumentation beschrieben. * **Verwendung des Tokens**: Sobald das Token erhalten wurde, sollte es für alle nachfolgenden API-Anfragen im HTTP-Header "Authorization" im Rahmen des "Bearer"-Schemas enthalten sein. Dieser Schritt ist unerlässlich, um Ihre Identität bei der API zu authentifizieren. * **Anfrageformat**: Alle anderen Anfragen, abgesehen von der Authentifizierungsanfrage, müssen dieses Token enthalten. Ein Beispiel dafür, wie das Token in einen Anfrage-Header aufgenommen wird, ist wie folgt: ```json Authorization: Bearer ``` {% hint style="info" %} Der Client sollte das aus der Authentifizierungsanfrage erhaltene JWT-Token lokal speichern und bis zu seinem Ablauf behalten. Das Ablaufdatum und die Uhrzeit des Tokens sind im Header des Tokens angegeben und bieten einen klaren Hinweis auf seinen gültigen Nutzungszeitraum. Um die Struktur eines JWT-Tokens zu verstehen und auf Bibliotheken für den Umgang mit JWT in verschiedenen Programmiersprachen zuzugreifen, können Sie besuchen . {% endhint %} ### Ressourcen Bei der Arbeit mit der Lucy-API beziehen sich "Ressourcen" auf die Daten, die Sie entweder aus der API abrufen oder die Objekte, die Sie über sie erstellen oder ändern. Die Struktur dieser Ressourcen bleibt unabhängig von der Art der von Ihnen ausgeführten Aktion gleich. Diese Einheitlichkeit stellt sicher, dass die Darstellung eines Objekts sich nicht ändert, egal ob Sie Informationen darüber abrufen oder es neu erstellen. Nehmen Sie "campaigns" als Beispiel: Die Datenstruktur, die Sie erhalten, wenn Sie alle Kampagnen auflisten oder eine einzelne Kampagne abfragen, bleibt dieselbe wie die, die der Server erwartet, wenn Sie eine Anfrage zum Erstellen einer neuen Kampagne senden. Der Hauptunterschied liegt im Umgang mit Links. Bei POST- oder PUT-Vorgängen (Erstellen oder Aktualisieren von Ressourcen) erwartet der Server keine Links innerhalb des Anfragekörpers und ignoriert sie, wenn sie enthalten sind. Diese Links werden ausschließlich in GET-Anfragen verwendet, um Beziehungen zwischen Ressourcen darzustellen. Um Beziehungen zu anderen vorhandenen Objekten im System zu definieren, wird empfohlen, ganzzahlige IDs zu verwenden. Dieser Ansatz vereinfacht den Zuordnungsprozess zwischen verschiedenen Ressourcen innerhalb der Lucy-API und sorgt für Klarheit und Konsistenz bei verschiedenen Vorgängen. ### API-Rückgabelimit für Datensätze Beim Abfragen von Lucy-API-Endpunkten, die eine Liste von Ressourcen zurückgeben, ist das Standardverhalten, maximal 100 Datensätze pro Anfrage zurückzugeben. Wenn Sie jedoch in einer einzelnen Anfrage mehr oder weniger Datensätze abrufen müssen, können Sie dies anpassen, indem Sie die `LIMIT` und `OFFSET` Anfrageparameter verwenden. Die maximale Anzahl von Datensätzen, die Sie mit dem `LIMIT` Parameter anfordern können, ist "1000". Wenn Sie einen `LIMIT` Wert größer als 1000 angeben, gibt die API weiterhin maximal 1000 Datensätze zurück, um Leistung und Systemstabilität zu gewährleisten. Diese Begrenzung stellt sicher, dass die API Anfragen effizient verarbeiten kann, ohne die Reaktionsfähigkeit des Servers zu beeinträchtigen. Um zu veranschaulichen, wie Sie die Anzahl der zurückgegebenen Datensätze anpassen können, betrachten Sie das folgende Beispiel: ```json GET /api/campaigns?sort=-created_at&offset=10&limit=10 ``` In diesem Beispiel `sort` Parameter ordnet die Kampagnen nach ihrem Erstellungsdatum in absteigender Reihenfolge (`-created_at`). Der `offset` Parameter wird verwendet, um die ersten 10 Datensätze zu überspringen, sodass die Liste effektiv beim 11. Datensatz beginnt. Der `limit` Parameter begrenzt dann die Anzahl der zurückgegebenen Datensätze auf 10. Diese Konfiguration ist besonders nützlich, um Paginierung zu implementieren oder bestimmte Datensegmente aus der Lucy-API abzurufen. ### Beispielverwendung 1. **Authentifizieren, um ein Token zu erhalten**: * **Anfrage**: ```json POST /api/auth HTTP/1.1 Host: phish.local Content-Type: application/json Cache-Control: no-cache {"email":"test@test.com","password":"123"} ``` * **Antwort**: ```json {"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9..."} ``` Verwenden Sie dieses Token im "Authorization"-Header für alle nachfolgenden Anfragen. 2. **Eine Empfängergruppe erstellen**: * **Anfrage**: ```json PUT /api/recipient-groups/ HTTP/1.1 Host: phish.local Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9... Content-Type: application/json Cache-Control: no-cache {"name":"test recipient group"} ``` * **Antwort**: ```json {"recipient-group":{"id":262,"name":"test recipient group","usb_attack":false,"links":[{"rel":"self","href":"/api/recipient-groups/262"}]}} ``` 3. **Einen Empfänger zur Gruppe hinzufügen**: * **Anfrage**: ```json PUT /api/recipient-groups/262/recipients HTTP/1.1 Host: phish.local Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9... Content-Type: application/json Cache-Control: no-cache {"email":"test@test.com","name":"Support Test"} ``` * **Antwort**: ```json {"recipient":{"email":"test@test.com","phone":null,"name":"Support Test"}} ``` Diese Abfolge demonstriert die grundlegenden Vorgänge, um sich zu authentifizieren, eine Empfängergruppe zu erstellen und einen Empfänger mithilfe der API zur Lucy-Plattform hinzuzufügen. Denken Sie daran, das Token, die E-Mail-Adressen, Namen und andere Details bei diesen Anfragen durch Ihre tatsächlichen Daten zu ersetzen. ### Detaillierte Dokumentation und Endpunkte {% hint style="info" %} Jeder Lucy-Server enthält einen Swagger-Client, der Administratoren das Erkunden und Testen von Endpunkten ermöglicht. Um auf den Swagger-Client zuzugreifen, navigieren Sie zu Einstellungen -> Allgemeine Systemeinstellungen -> Abschnitt API-Whitelist und wählen Sie **API-Dokumentation**. ![](/files/98d77beb8b883ca614c8fc8b928eabeecbd0c9f6) {% endhint %} Ein Swagger-API-Client ist eine Softwarebibliothek oder ein Tool, das aus einer Swagger-Spezifikation generiert wird und dazu dient, die Kommunikation mit einer Web-API zu erleichtern, die durch diese Spezifikation beschrieben wird. Swagger, heute als OpenAPI bekannt, ist ein weit verbreitetes Framework für die API-Entwicklung und bietet eine Reihe von Tools zum Entwerfen, Erstellen, Dokumentieren und Nutzen von RESTful-Webdiensten. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.lucysecurity.com/lucy-wiki-de/anwendungsreferenz/einstellungen/allgemeine-systemeinstellungen/api-whitelist.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.