Authentifizierungs-API

ENTWURF — Nur für interne Entwickler

Diese API-Referenz ist für interne Entwicklungsteams bestimmt.

Übersicht

Was es ist: Die Authentifizierungs-API bietet tokenbasierten Zugriff auf alle Discovery-Endpunkte. Je nach Integrationstyp stehen drei Methoden zur Verfügung.

Warum es wichtig ist: Jeder API-Aufruf erfordert ein gültiges Token. Service-zu-Service-Integrationen wie Hydden Control verwenden API-Anmeldeinformationen, während interaktive Sitzungen OTP oder OAuth nutzen können.

Endpunkte

Token-Generierung

Methode	Pfad	Beschreibung	Authentifizierung erforderlich
POST	/auth/api	Authentifizierung mit API-Anmeldeinformationen	Keine (Anmeldeinformationen im Body)
POST	/auth/otp	Authentifizierung mit Einmalpasswort	Keine (Anmeldeinformationen im Body)
POST	/oauth/token	OAuth 2.0-Token-Endpunkt	Basic-Auth-Header

Token-Verwaltung

Methode	Pfad	Beschreibung	Authentifizierung erforderlich
GET	/internal/v1/token/renew	Ein ablaufendes Zugriffstoken erneuern	JWT-Cookie
GET	/internal/v1/user/info	Informationen zum aktuell authentifizierten Benutzer abrufen	JWT-Cookie
GET	/internal/v1/version	API-Version abrufen	JWT-Cookie
GET	/internal/v1/features	Aktivierte Feature-Flags abrufen	JWT-Cookie

OIDC-Provider-Verwaltung

Methode	Pfad	Beschreibung	Authentifizierung erforderlich
GET	/internal/v1/oidc/providers	OIDC-Provider auflisten	JWT-Cookie
GET	/internal/v1/oidc/registration	Registrierungsstatus abrufen	JWT-Cookie
POST	/internal/v1/oidc/registration/accept	OIDC-Registrierung akzeptieren	JWT-Cookie
POST	/internal/v1/oidc/registration/reject	OIDC-Registrierung ablehnen	JWT-Cookie
GET	/internal/v1/oidc/registration/join	OIDC-Registrierungs-Beitrittsablauf	JWT-Cookie

Zugriffskontrolle

Methode	Pfad	Beschreibung	Authentifizierung erforderlich
GET	/internal/v1/access/role	Aktuelle Benutzerrolle und Berechtigungen abrufen	JWT-Cookie
GET	/internal/v1/access/role/*action	Berechtigung für eine bestimmte Aktion prüfen	JWT-Cookie

Nonce

Methode	Pfad	Beschreibung	Authentifizierung erforderlich
GET	/auth/nonce/:nonce	Einen Nonce-Wert abrufen	Keine
POST	/auth/nonce	Einen neuen Nonce erstellen	Keine

---

POST /auth/api

Authentifizierung mit API-Client-Anmeldeinformationen. Dies ist die primäre Methode für die Service-zu-Service-Kommunikation.

Anfrage:

POST /auth/api
Content-Type: application/json

{
  "id": "your-client-id",
  "secret": "your-client-secret",
  "code": "optional-tenant-code"
}

Antwort (200):

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

Fehlerantworten:

Code	Grund
401	Ungültige Anmeldeinformationen
403	Client deaktiviert oder Mandantenkonflikt

Control-Integration

Hydden Control authentifiziert sich über diesen Endpunkt. Der HTTPClient sendet ClientID und ClientSecret aus den verschlüsselten Integrationseinstellungen:

// Control's authentication flow (simplified)
POST {DiscoveryBaseURL}/auth/api
Body: {"id": clientID, "secret": decryptedSecret}

// Token is cached per tenant with TTL from expiresIn
// Automatic retry with exponential backoff on 429/5xx

Control speichert Tokens pro Mandant zwischen und erneuert sie vor Ablauf. Der Token-Cache verwendet einen Lese-/Schreib-Mutex für Thread-Sicherheit.

---

POST /auth/otp

Authentifizierung mit einem Einmalpasswort.

Anfrage:

POST /auth/otp
Content-Type: application/json

{
  "id": "user-identifier",
  "secret": "otp-secret",
  "code": "one-time-code"
}

Antwort: Gleiches Format wie /auth/api.

---

POST /oauth/token

Standard-OAuth-2.0-Token-Endpunkt. Unterstützt Basic-Auth-Header für Client-Anmeldeinformationen.

Anfrage:

POST /oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Antwort (200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

---

GET /internal/v1/token/renew

Das aktuelle Zugriffstoken vor Ablauf erneuern. Erfordert eine aktive JWT-Cookie-Sitzung.

Anfrage:

GET /internal/v1/token/renew
Cookie: jwt=<current-token>

Antwort (200):

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "expiresIn": 3600
}

---

GET /internal/v1/user/info

Informationen zum aktuell authentifizierten Benutzer abrufen.

Anfrage:

GET /internal/v1/user/info
Authorization: Bearer <token>

Antwort (200):

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "role": "admin",
  "tenantId": "tenant-uuid"
}