Discovery API-Referenz

ENTWURF — Nur für interne Entwickler

Diese API-Referenz ist für interne Entwicklungsteams bestimmt. Sie ist noch nicht für die externe Nutzung veröffentlicht.

Übersicht

Was es ist: Die Hydden Discovery-Plattform stellt eine REST-API für den programmatischen Zugriff auf Funktionen zur Identitätserkennung, -erfassung, Automatisierung und Governance bereit. Andere Hydden-Produkte wie Control nutzen diese Endpunkte zur Synchronisierung von Identitätsdaten.

Warum es wichtig ist: Interne Entwickler, die Integrationen zwischen Hydden-Produkten erstellen, benötigen eine klare Referenz für verfügbare Endpunkte, Authentifizierungsmethoden und Datenformate.

Basis-URLs

Discovery organisiert seine API in zwei Routengruppen:

Routenpräfix	Zweck	Authentifizierung
/api/v1/	Öffentliche API — externe Integrationen und produktübergreifende Aufrufe	JWT-Cookie + API-Token + CORS
/internal/v1/	Interne API — Plattformverwaltung und -konfiguration	JWT-Cookie + API-Token + CORS

Beide Präfixe erfordern eine Authentifizierung. Der Präfix /api/v1/ ist die primäre Integrationsschnittstelle für andere Hydden-Produkte.

Authentifizierung

Hydden unterstützt drei Authentifizierungsmethoden. Siehe die Authentifizierungsreferenz für vollständige Details.

Methode	Endpunkt	Anwendungsfall
API-Anmeldeinformationen	POST /auth/api	Service-zu-Service-Aufrufe (z. B. Control synchronisiert Daten)
Einmalpasswort	POST /auth/otp	Kurzlebige interaktive Sitzungen
OAuth 2.0	POST /oauth/token	Standard-OAuth-Flows mit Basic-Auth-Header

Token-Format: Alle Methoden geben ein Bearer-Token zurück. Fügen Sie es in nachfolgende Anfragen ein:

GET /api/v1/dashboard/status
Authorization: Bearer <token>

Wie Control sich authentifiziert: Hydden Control verwendet POST /auth/api mit einem ClientID- und ClientSecret-Paar, das in verschlüsselten Integrationseinstellungen gespeichert ist. Das Token wird pro Mandant zwischengespeichert und vor Ablauf automatisch erneuert. Siehe Control-Integrationsmuster unten.

API-Module

Modul	Pfadpräfix	Beschreibung
Authentifizierung	/auth/, /oauth/	Token-Generierung und OIDC-Provider-Verwaltung
Identität	/internal/v1/entity/, /internal/v1/collector/	Entitätsabfragen, Collector-Konfigurationen, Connector-Vorlagen
Automatisierung	/api/v1/actions, /api/v1/workflows	Aktionen, Workflows, Auslöser und Anmeldeinformationen
KI	/internal/v1/ai/	KI-Autovervollständigung, Agenten-Sitzungen, Vektorspeicher
Attestierung	/internal/v1/attest/	Zertifizierungen, Attestierungseinstellungen und -typen
Suche	/api/v1/global/	SSRM-Abfrage und globale Suchendpunkte
Dashboard	/api/v1/dashboard/	Dashboard-Status und Kontometadaten
Tresor	/internal/v1/vault/	Handler für den Anmeldeinformationstresor und Kontoverwaltung
Universal Connector	/internal/v1/connector/universal/	Benutzerdefinierte Connector-Schemata und Zuordnungen
System	/internal/v1/registry/, /internal/v1/license/	Registrierung, Lizenzierung, Audit, Datenspeicher, Benachrichtigungen

Middleware-Stack

Jede Anfrage durchläuft diese Middleware-Schichten (in Reihenfolge angewendet):

Diagrammbeschreibung: Ein Top-Down-Flussdiagramm, das den API-Middleware-Stack zeigt. Eine Client-Anfrage durchläuft nacheinander den Request Logger, CORS Handler, JWT Cookie Auth, API Authenticator und Compressor, bevor sie den Route Handler erreicht.

1. Request Logger — Erfasst Metriken für die Überwachung
2. CORS Handler — Validiert Cross-Origin-Anfragen
3. JWT Cookie — Extrahiert und validiert JWT aus Cookies
4. API Authenticator — Validiert API-Schlüssel oder Bearer-Token
5. Compressor — Komprimiert Antworten (gzip, deflate, br)

Allgemeine Antwortmuster

Erfolgreiche Antwort:

{
  "data": { ... },
  "totalCount": 150,
  "viewTime": "2026-02-12T10:00:00Z"
}

Fehlerantwort:

{
  "error": "unauthorized",
  "message": "Invalid or expired token",
  "code": 401
}

Standard-HTTP-Statuscodes:

Code	Bedeutung
200	Erfolg
201	Erstellt
204	Kein Inhalt (erfolgreiche Löschung)
400	Ungültige Anfrage — Anfragekörper prüfen
401	Nicht autorisiert — Token fehlt oder abgelaufen
403	Verboten — unzureichende Berechtigungen
404	Nicht gefunden
429	Ratenbegrenzung — mit Backoff erneut versuchen
500	Interner Serverfehler

Paginierung

Endpunkte, die Listen zurückgeben, unterstützen serverseitige Paginierung über den Anfragekörper:

{
  "offset": 0,
  "limit": 100,
  "filterModel": {},
  "sortModel": [],
  "rowGroupCols": [],
  "groupKeys": []
}

Die Antwort enthält totalCount zur Berechnung der Seitenanzahl.

Control-Integrationsmuster

Hydden Control integriert sich über einen dedizierten HTTP-Client mit Discovery. Wichtige Muster:

Aspekt	Detail
Authentifizierung	POST /auth/api mit ClientID + verschlüsseltem ClientSecret pro Mandant
Token-Caching	Token-Cache pro Mandant mit automatischer Erneuerung vor Ablauf
Wiederholungslogik	Exponentielles Backoff für HTTP 429, 502, 503, 504 (max. 3 Versuche)
Kompression	Anfragen akzeptieren gzip, deflate und brotli
User-Agent	Hydden-LiteIGA/1.0
Paginierung	POST-Körper mit offset und limit, iteriert bis totalCount erreicht ist
Mandantenisolierung	Jeder Aufruf ist über kontextbasierte Einstellungssuche auf einen einzelnen Mandanten beschränkt

Diagrammbeschreibung: Ein Sequenzdiagramm, das zeigt, wie Control sich mit der Discovery-API integriert. Das Control-Backend authentifiziert sich bei Discovery über POST /auth/api mit ClientID und Secret, erhält ein Bearer-Token, das pro Mandant zwischengespeichert wird, und sendet dann eine SSRM-Abfrage zum Abrufen von Spalten, Zeilen und Gesamtanzahl. Control ordnet Discovery-Felder seinen eigenen Modellen zu und speichert die Daten in einem lokalen Repository.

Verwendung von Postman oder anderen API-Clients

Um auf die vollständige interaktive API-Referenz zuzugreifen, navigieren Sie zur OpenAPI-Seite Ihres Portals:

https://<your-portal>.hydden.com/openapi/index.html

Um ein API-Token für die Authentifizierung zu erstellen, siehe API-Tokens.