Authentifizierungs-API

Die Authentifizierungs-API verarbeitet alle Identitätsverifizierungsflüsse: E-Mail/Passwort-Anmeldung, Registrierung, Token-Aktualisierung, Magic Links, Zwei-Faktor-Authentifizierung und den OAuth2-AutorisierungsCode-Fluss. Öffentliche Endpunkte benötigen keinen Authorization-Header; Benutzer- und Admin-Endpunkte schon.

E-Mail / Passwort

POST/api/auth/login

Benutzer mit E-Mail und Passwort authentifizieren. Gibt ein Zugriffs-Token, Refresh-Token, Sitzungs-ID und Token-Ablaufzeit zurück. Wenn der Tenant oder die Anwendung 2FA erfordert und der Benutzer 2FA konfiguriert hat, gibt die Antwort an, dass ein zweiter Faktor erforderlich ist, bevor Token ausgestellt werden.

Anforderungs-Body


{
  "email": "[email protected]",
  "password": "geheim123"
}

Erfolgsantwort (kein 2FA erforderlich)


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "sessionId": "sess_abc123",
    "tokenType": "Bearer"
  }
}

Erfolgsantwort (2FA erforderlich)


{
  "ok": true,
  "data": {
    "requiresTwoFactor": true,
    "sessionId": "sess_abc123",
    "availableMethods": ["totp", "sms"]
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`INVALID_CREDENTIALS`	401	E-Mail oder Passwort ist falsch
`ACCOUNT_LOCKED`	403	Konto ist aufgrund wiederholter Fehler gesperrt
`ACCOUNT_DISABLED`	403	Konto wurde von einem Administrator deaktiviert
`RATE_LIMITED`	429	Zu viele Anmeldeversuche

POST/api/auth/signup

Ein neues Benutzerkonto registrieren. Der Tenant muss Registrierung aktiviert haben. Bei Erfolg wird dieselbe Token-Struktur wie bei der Anmeldung zurückgegeben. Wenn E-Mail-Verifizierung vom Tenant erfordert wird, wird eine E-Mail gesendet und der Benutzer kann sich erst nach der Verifizierung anmelden.

Anforderungs-Body


{
  "email": "[email protected]",
  "password": "sicherespasswort",
  "firstName": "Jana",
  "lastName": "Doe"
}

firstName und lastName sind optional. password ist erforderlich, es sei denn, der Tenant ist für reine Passwortlos-Registrierung konfiguriert.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "sessionId": "sess_xyz789",
    "tokenType": "Bearer"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`EMAIL_TAKEN`	409	Ein Konto mit dieser E-Mail existiert bereits
`SIGNUP_DISABLED`	403	Der Tenant hat die öffentliche Registrierung deaktiviert
`WEAK_PASSWORD`	400	Passwort erfüllt Stärkeanforderungen nicht
`VALIDATION_ERROR`	400	Anforderungs-Body hat Schemavalidierung nicht bestanden

Token-Endpunkt (OAuth2)

POST/api/auth/token

OAuth2-Token-Endpunkt. Unterstützt mehrere Grant-Typen: Authorization Code (mit PKCE), Client Credentials (M2M) und Device Code. Die Anforderungs-Body-Form unterscheidet sich je nach Grant-Typ.

Dieser Endpunkt ist der im OIDC-Discovery-Dokument referenzierte Standard-OAuth2-Token-Endpunkt. Er akzeptiert application/json- oder application/x-www-form-urlencoded-Anforderungs-Bodies.

Grant: Authorization Code + PKCE

Wird verwendet, um einen Autorisierungscode (aus der gehosteten Login-Weiterleitung) gegen Token einzutauschen. Der code_verifier ist der ursprüngliche Zufallswert, aus dem der code_challenge abgeleitet wurde.

Anforderungs-Body


{
  "grant_type": "authorization_code",
  "code": "auth_code_from_redirect",
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk",
  "redirect_uri": "https://app.ihredomain.de/callback",
  "client_id": "ihre-client-id"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "idToken": "eyJhbGciOiJSUzI1NiJ9...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`CODE_INVALID`	400	Autorisierungscode existiert nicht oder ist abgelaufen
`CODE_USED`	400	Autorisierungscode wurde bereits ausgetauscht (Einmalverwendung)
`PKCE_MISMATCH`	400	`SHA256(code_verifier)` stimmt nicht mit der gespeicherten Challenge überein
`REDIRECT_URI_MISMATCH`	400	`redirect_uri` stimmt nicht mit der registrierten URI überein

Grant: Client Credentials (M2M)

Wird für Maschine-zu-Maschine-Authentifizierung verwendet, bei der kein Benutzer beteiligt ist. Der Client authentifiziert sich mit seiner client_id und seinem client_secret.

Anforderungs-Body


{
  "grant_type": "client_credentials",
  "client_id": "m2m-client-id",
  "client_secret": "m2m-client-secret",
  "scope": "read:users manage:roles"
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "expiresIn": 3600,
    "tokenType": "Bearer",
    "scope": "read:users manage:roles"
  }
}

Grant: Device Code (RFC 8628)

Wird für Geräte verwendet, die keinen Browser anzeigen können (CLIs, IoT, Smart-TVs). Zuerst fordert das Gerät einen Gerätecode an; der Benutzer besucht dann die Verifizierungs-URL auf einem separaten Gerät und genehmigt. Das Gerät fragt ab, bis es genehmigt wird.

Anforderungs-Body (Polling)


{
  "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "client_id": "ihre-client-id"
}

Ausstehende Antwort (Benutzer hat noch nicht genehmigt)


{
  "ok": false,
  "error": {
    "code": "AUTHORIZATION_PENDING",
    "message": "Der Benutzer hat die Anforderung noch nicht genehmigt. Polling fortsetzen."
  }
}

Token-Verwaltung

POST/api/auth/refresh

Ein Refresh-Token gegen ein neues Zugriffs-Token und ein neues Refresh-Token austauschen. Refresh-Token werden bei jeder Verwendung rotiert — das alte Refresh-Token wird sofort ungültig.

Anforderungs-Body


{
  "refreshToken": "rt_..."
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_new...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`REFRESH_TOKEN_INVALID`	401	Token existiert nicht oder wurde widerrufen
`REFRESH_TOKEN_EXPIRED`	401	Token hat seine Ablaufzeit überschritten

POST/api/auth/validateRequires: authenticated user

Das aktuelle Zugriffs-Token validieren und die Informationen des authentifizierten Benutzers zurückgeben. Dieser Endpunkt ist auch der OIDC-UserInfo-Endpunkt.

Anforderung: Kein Body erforderlich. Das Zugriffs-Token wird aus dem Authorization: Bearer-Header gelesen.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "valid": true,
    "userId": "usr_abc123",
    "email": "[email protected]",
    "username": "jana.doe",
    "firstName": "Jana",
    "lastName": "Doe",
    "roles": ["viewer", "billing-admin"],
    "tenant": "acme-corp"
  }
}

POST/api/auth/logoutRequires: authenticated user

Die aktuelle Sitzung ungültig machen. Das mit der Sitzung verbundene Refresh-Token wird widerrufen. Das Zugriffs-Token bleibt bis zum natürlichen Ablauf gültig (JWTs werden standardmäßig nicht geblockt — verlasse dich auf kurze Ablaufzeiten).

Anforderung: Kein Body erforderlich.

Erfolgsantwort


{
  "ok": true,
  "data": { "loggedOut": true }
}

Magic Links (Passwortlos)

POST/api/auth/magic-link

Einen Magic Link (Passwortlose Anmelde-E-Mail) an die angegebene Adresse senden. Wenn kein Konto existiert und allowSignup in der Passwortlos-Konfiguration des Tenants aktiviert ist, wird beim Klicken auf den Link automatisch ein neues Konto erstellt.

Anforderungs-Body


{
  "email": "[email protected]",
  "redirectUrl": "https://app.ihredomain.de/callback"
}

redirectUrl ist optional; fällt auf die konfigurierte Standard-Redirect-URL des Tenants zurück.

Erfolgsantwort


{
  "ok": true,
  "data": { "sent": true }
}

Die Antwort ist immer { sent: true }, unabhängig davon, ob die E-Mail existiert, um Benutzerenumeration zu verhindern.

POST/api/auth/magic-link/verify

Ein Magic-Link-Token verifizieren. Automatisch von der gehosteten Anmeldeseite aufgerufen, wenn der Benutzer auf den Link klickt. Gibt bei Erfolg Token zurück.

Anforderungs-Body


{
  "token": "mlnk_..."
}

Erfolgsantwort


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`MAGIC_LINK_INVALID`	400	Token ist fehlerhaft oder existiert nicht
`MAGIC_LINK_EXPIRED`	400	Token ist abgelaufen (Standard-Ablauf: 15 Minuten)
`MAGIC_LINK_USED`	400	Token wurde bereits verbraucht (Einmalverwendung)

Passwort-Reset

POST/api/auth/forgot-password

Einen Passwort-Reset-Fluss initiieren. Sendet eine E-Mail mit einem Reset-Link an die angegebene Adresse. Die Antwort ist immer erfolgreich, um Benutzerenumeration zu verhindern.

Anforderungs-Body


{
  "email": "[email protected]"
}

Erfolgsantwort


{
  "ok": true,
  "data": { "sent": true }
}

Zwei-Faktor-Authentifizierung

POST/api/auth/verify-2fa

Einen zweiten Faktor nach der initialen Passwort-Authentifizierung verifizieren. Diesen mit der von der Anmeldung zurückgegebenen Sitzungs-ID (wenn requiresTwoFactor: true) und dem OTP-Code oder der WebAuthn-Antwort aufrufen. Bei Erfolg werden vollständige Zugriffs- und Refresh-Token zurückgegeben.

Anforderungs-Body — TOTP


{
  "sessionId": "sess_abc123",
  "code": "123456",
  "method": "totp"
}

Anforderungs-Body — SMS OTP


{
  "sessionId": "sess_abc123",
  "code": "789012",
  "method": "sms"
}

Anforderungs-Body — WebAuthn


{
  "sessionId": "sess_abc123",
  "method": "webauthn",
  "response": { }
}

response ist das AuthenticatorAssertionResponse-Objekt aus der WebAuthn-Browser-API.

Erfolgsantwort


{
  "ok": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiJ9...",
    "refreshToken": "rt_...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

Fehlercodes

Code	HTTP	Beschreibung
`INVALID_OTP`	400	Der angegebene Code ist falsch
`OTP_EXPIRED`	400	Der Code ist abgelaufen
`SESSION_INVALID`	400	Die Sitzungs-ID ist ungültig oder bereits verbraucht
`WEBAUTHN_FAILED`	400	WebAuthn-Assertion-Verifizierung fehlgeschlagen

GET/api/auth/check-2fa-requiredRequires: authenticated user

Überprüfen, ob die aktuelle Sitzung eine 2FA-Verifizierung erfordert, bevor vollständiger Zugriff gewährt wird. Nützlich zum Absichern von Seiten nach der initialen Anmeldung, um sicherzustellen, dass der Benutzer den vollständigen Fluss abgeschlossen hat.

Antwort


{
  "ok": true,
  "data": {
    "required": false,
    "verified": true,
    "availableMethods": ["totp", "sms"]
  }
}

SSO-Erkennung

POST/api/auth/sso/detect

Erkennen, ob die E-Mail-Domain eines Benutzers eine Enterprise-SSO-Verbindung konfiguriert hat. Verwende dies zur Implementierung “intelligenter” Anmeldeformulare, die Enterprise-Benutzer automatisch zu ihrem SSO-Anbieter weiterleiten, anstatt das Passwortfeld anzuzeigen.

Anforderungs-Body


{
  "email": "[email protected]"
}

Antwort — SSO verfügbar


{
  "ok": true,
  "data": {
    "ssoAvailable": true,
    "provider": "saml",
    "loginUrl": "https://ihre-auris-domain.de/api/auth/sso/login/enterprise-alias"
  }
}

Antwort — kein SSO


{
  "ok": true,
  "data": {
    "ssoAvailable": false,
    "provider": null,
    "loginUrl": null
  }
}

OAuth2-Autorisierungsendpunkt

POST/api/oauth/authorize

Einen OAuth2-Authorization-Code-+PKCE-Fluss starten. Dieser Endpunkt erstellt eine Sitzung und leitet den Benutzer zur gehosteten Auris-Anmeldeseite weiter. Bei erfolgreicher Authentifizierung leitet Auris zur registrierten redirect_uri mit einem Autorisierungscode weiter.

Dies wird typischerweise als Browser-Weiterleitung (GET oder Formular-POST) ausgelöst, nicht als Fetch-Aufruf. Die SDK-Methode loginWithRedirect() übernimmt dies alles automatisch.

Parameter (Query-String oder Anforderungs-Body)

Parameter	Erforderlich	Beschreibung
`response_type`	Ja	Muss `"code"` sein
`client_id`	Ja	Anwendungs-Client-ID
`redirect_uri`	Ja	Callback-URL (muss registriert sein)
`state`	Ja	Zufälliges CSRF-Token
`code_challenge`	Ja	BASE64URL(SHA256(code_verifier))
`code_challenge_method`	Ja	Muss `"S256"` sein
`scope`	Nein	Leerzeichen-getrennte Scopes (z. B. `openid profile email`)
`login_hint`	Nein	Das E-Mail-Feld vorab ausfüllen
`screen_hint`	Nein	`"signup"` um zuerst den Registrierungsbildschirm anzuzeigen
`locale`	Nein	Eine bestimmte Sprache erzwingen (`en`, `it`, `de`, `fr`, `es`)
`prompt`	Nein	`"login"` um Re-Authentifizierung zu erzwingen

Weiterleitung bei Erfolg


https://app.ihredomain.de/callback?code=auth_code_xxx&state=original_state

Weiterleitung bei Fehler


https://app.ihredomain.de/callback?error=access_denied&error_description=User+cancelled&state=original_state

Fehlercodes (als Weiterleitungsparameter zurückgegeben)

Code	Beschreibung
`invalid_request`	Fehlender oder ungültiger Parameter
`unauthorized_client`	`client_id` nicht gefunden oder `redirect_uri` nicht registriert
`access_denied`	Benutzer hat Authentifizierung abgebrochen
`invalid_scope`	Angeforderter Scope ist nicht erlaubt

Zugehörige Referenzen

OAuth 2.0 & OIDC — Protokollgrundlagen hinter den Authentifizierungsendpunkten
Tokens erklärt — Zugriffs-Token, Refresh-Token und ID-Token im Detail
PKCE-Flow — Wie der Authorization-Code-+PKCE-Austausch funktioniert
Gehostete Anmeldeanleitung — Gehostete Anmeldung in deine Anwendung integrieren
Magic Links — Passwortlose E-Mail-Authentifizierung
Social Login — Drittanbieter-Identitätsanbieter konfigurieren
M2M Client Credentials — Server-zu-Server-Authentifizierung
Authentifizierungseinstellungen — MFA, Passwortlos und Social Login in der Konsole konfigurieren