HEIMDAL Security API 2.0

HEIMDAL Security ermöglicht Ihnen den einfachen Zugriff auf Daten zu Ihren Endpunkten, die Anzeige erkannter Bedrohungen, Anwendungsbereitstellungen und mehr. Dafür stellen wir API-Endpunkte bereit, mit denen Sie die in unserem HEIMDAL Dashboard verfügbaren Daten in jedes gewünschte SIEM-Tool übernehmen können.

Um auf den HEIMDAL-API-Bereich zuzugreifen, melden Sie sich beim HEIMDAL Dashboard an und klicken Sie auf die Registerkarte Guide -> Mini-Registerkarte Your Heimdal API Key . Ihr persönlicher API-Schlüssel kann im Abschnitt Guide -> Your Personal API Key generiert werden. Wenn Sie keinen aktiven persönlichen API-Schlüssel haben, können Sie im Abschnitt Guide -> Your Heimdal API Key einen generieren. Falls Sie den vorhandenen persönlichen API-Schlüssel löschen müssen, können Sie auf die Schaltfläche Delete klicken und einen neuen persönlichen API-Schlüssel generieren. 

1. Authentifizierung der API 2.0
2. Konfiguration der API 2.0
3. Endpunkte der API 2.0

AUTHENTIFIZIERUNG DER API 2.0

Die Endpunkte der API 2.0 ermöglichen es Ihnen, die im HEIMDAL Dashboard verfügbaren Daten für jedes HEIMDAL-Produkt im JSON-Format abzurufen (über die Methoden GET, POST und PUT). Die Daten können mithilfe der unten beschriebenen Parameter gefiltert und mit Ihrem persönlichen API-Schlüssel abgerufen werden, der dem Authentication-Header als Authentifizierungstyp Bearer oder OAUTH2 hinzugefügt wird. Der Zugriff auf die API-Endpunkte ist nur von IP-Adressen/-Bereichen möglich, die für Ihr HEIMDAL-Dashboard-Benutzerkonto als vertrauenswürdig markiert sind (im Abschnitt „Accounts“).

Bei jeder HTTP-Anfrage an die Heimdal-Security-API müssen Sie Ihren persönlichen API-Schlüssel im HTTP-Header Authorization angeben: "Authorization: Bearer Your-Personal-API-Key".

Curl

curl -H "Authorization: Bearer USP5MERX4PRNZ3FU7RMYUTBL52ASIORN" "https://dashboard.heimdalsecurity.com/api/heimdalapi/2.0/activeclients?customerId=229584&startDate=2021-04-03T12:00&endDate=2021-05-03T11:59&pageNumber=1&pageSize=1000"

KONFIGURATION DER API 2.0

Die Endpunkte der Heimdal API v2.0 sind normalerweise nach Modulen strukturiert. Die Basis-URL hängt von Ihrer spezifischen HEIMDAL-Dashboard-Umgebung ab (z. B. PROD oder RC). Eine typische GET-Anfrage zum Abrufen von Daten (z. B. Details zu Geräteinformationen) folgt diesem Muster:

Abfrageparameter des Befehls:

• customerId: (Erforderlich) Ihre eindeutige Kundenidentifikationsnummer.
• startDate / endDate: Filtert Ergebnisse innerhalb eines bestimmten Zeitraums (Format: YYYY-MM-DDTHH:MM:SS).
• optional_parameter: Spezifische Filter wie hostname, email oder status.

Beispiel:

curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://dashboard.heimdalsecurity.com/api/heimdalapi/2.0/activeclients?customerId=9999"

Erwartete Ausgabe (JSON-Antwort)
Die API gibt Daten im JSON-Format zurück. Eine erfolgreiche Anfrage gibt den Statuscode 200 OK mit einem Antworttextkörper zurück, der wie folgt strukturiert ist:

{
 "result": [
   {
     "id": "307508",
     "hostname": "WORKSTATION-01",
     "os": "Windows 11",
     "agentVersion": "4.2.0",
     "status": "Active",
     "lastSeen": "2024-12-17T10:00:00"
   }
 ],
 "status": "RanToCompletion",
 "isCompletedSuccessfully": true
}

Einschränkungen und Standardparameter der API 2.0

Um eine hohe Verfügbarkeit und optimale Leistung in unserer Infrastruktur sicherzustellen, gelten für die HEIMDAL-API die folgenden Nutzungsrichtlinien:

• Ratenbegrenzung: Die API erlaubt bis zu 10 Anfragen pro Minute, pro Endpunkt, pro API-Schlüssel und pro Kunden-ID.
• Granularität: Die Einschränkungen werden auf einer fein abgestuften Ebene angewendet, um eine flexible Integration zu ermöglichen. Die Drosselung wird pro API-Schlüssel, pro Kunden-ID und pro Route berechnet. Für Partner oder Wiederverkäufer bedeutet dies, dass die Limits auf jede spezifische Kundenumgebung und Produkt-„Quelle“ isoliert sind, sodass eine hohe Nutzung in einem Bereich keine Auswirkungen auf andere Bereiche hat.
• Seitennummerierung: Für einen effizienten Datenabruf beträgt die Standardseitengröße 1.000 Datensätze pro Seite (zuvor 100), wodurch die Gesamtzahl der für große Datensätze erforderlichen Roundtrips reduziert wird.

Die folgenden Parameter werden in den meisten Datenabrufanfragen der Heimdal-API verwendet.

Hinweis: Wenn Sie das Ratenlimit überschreiten, gibt die API den HTTP-Statuscode 429 Too Many Requests zurück. Wir empfehlen, eine Wiederholungslogik mit exponentiellem Backoff zu implementieren, um diese Fälle ordnungsgemäß zu behandeln.

API-ENDPUNKTE

Kundendetails

Dieser API-Endpunkt ruft Informationen zu einem bestimmten Kunden oder zu allen Kunden eines Wiederverkäufers ab. Er funktioniert nur, wenn Sie im Dashboard die Rolle „Reseller“, „Admin“ oder „Super Admin“ haben und die ID des Kunden oder Wiederverkäufers als Wert für customerId angeben.

{
    "items": [
        {
            "id": 229584,
            "name": "HEIMDAL Support Team",
            "customerType": "Corp",
            "licenseType": "DNS-N,DNS-E,VM,IM,AV,REP,PEDM,AC,ESEC,EFP,RD,PASM",
            "splaLicense": "No",
            "purchasedLicenses": 100
        }
    ],
    "totalCount": 1,
    "pageNumber": 1,
    "pageSize": 1000
}

Details zu Geräteinformationen

Dieser API-Endpunkt ruft Informationen zu allen aktiven Clients eines Kunden ab (ID, Hostname, IP-Adresse, Agent-Version, Betriebssystem, aktuelle Gruppenrichtlinie, zuletzt gesehen, aktive Module, Status).

{
    "items": [
        {
            "id": 743907,
            "hostname": "SUPPORT1",
            "username": "Test",
            "ipAddress": "10.0.2.52",
            "externalIp": "5.2.145.131",
            "version": "4.5.0.2000",
            "currentGroupPolicy": "3rd Party Patch Management",
            "selectedGroupPolicyId": 39299,
            "lastSeen": "2024-12-12T18:11:27.843+00:00",
            "modules": "ThirdParty Applications,Infinity Management,Scripting",
            "status": "Active",
            "machineType": "Endpoint",
            "operatingSystem": "Microsoft Windows 10 Enterprise - x64",
            "motherboardSerial": "6123-2686-6273-8851-1549-0354-63",
            "motherboardSerialSecondary": "6123-2686-6273-8851-1549-0354-63",
            "hddSerial": "",
            "previousGroupPolicy": "",
            "lastPolicyChange": "0001-01-01T00:00:00+00:00"
        }
    ]
}