API-Authentifizierung

octoja verwendet JWT-basierte Authentifizierung für API-Clients und ein HTTP-Session-Cookie für browserbasierte Abläufe.

Nach einem erfolgreichen Login oder Refresh enthält der Response-Body ein accessToken und ein refreshToken, zusammen mit tokenType und expiresIn (Lebensdauer des Access-Tokens in Sekunden). Browserbasierte Anmeldungen erhalten zusätzlich das Session-Cookie octo_session.

Login

POST /api/auth/login

Request Body

Beispiel-Request

{ "mailAddress": "alex@example.com", "password": "example-password", "TOTP": "123456" }

Erfolgreiche Antwort

{ "tokenType": "Bearer", "accessToken": "eyJ...", "expiresIn": 3600, "refreshToken": "eyJ..." }

Refresh

POST /api/auth/refresh

Ein gültiges Refresh-Token gegen ein neues Token-Paar eintauschen.

Request Body

Beispiel-Request

{ "refreshToken": "eyJ..." }

Erfolgreiche Antwort

{ "tokenType": "Bearer", "accessToken": "eyJ...", "expiresIn": 3600, "refreshToken": "eyJ..." }

Logout

POST /api/auth/logout

Meldet die aktuelle Browser-Sitzung ab und löscht das octo_session-Cookie.

Access-Token verwenden

Schicke das Access-Token im Authorization-Header bei authentifizierten API-Anfragen mit:

Authorization: Bearer <access_token>Content-Type: application/json

Um die API interaktiv zu erkunden, öffne die OpenAPI-Oberfläche (Swagger) unter https://<deine-octoja-instanz>/openapi/index.html, klicke auf Authorize und füge dein Access-Token ein. Swagger sendet dann den Authorization-Header für dich, sodass du authentifizierte Anfragen ohne eigenen Code ausprobieren kannst.

OIDC / SSO Login

Für browserbasiertes Single Sign-On unterstützt octoja OIDC-Anbieter wie Microsoft.

Verfügbare Anbieter ermitteln

GET /api/auth/oidc/providers

Gibt die Liste der für deine Organisation konfigurierten OIDC-Anbieter zurück. Damit kannst du vor dem Starten eines Logins prüfen, welche Anbieternamen gültig sind.

Login starten

1. Rufe GET /api/auth/oidc/{provider}/authorize?returnUrl=<your-frontend-url> auf.
2. Der Endpoint gibt ein JSON-Objekt mit der Login-URL des Anbieters zurück.
3. Leite den Benutzer zu dieser URL weiter.
4. Nach Abschluss des Anbieter-Logins wird der Browser an /api/auth/oidc/callback weitergeleitet.
5. Wenn für den angemeldeten Benutzer keine Zwei-Faktor-Authentifizierung aktiviert ist, setzt das Backend die Sitzung und leitet den Browser zurück zur ursprünglichen returnUrl. Ist TOTP für den Benutzer aktiviert, wird noch keine Sitzung ausgestellt: Der Browser wird an die Frontend-Route /login mit einem oidcTotpPending-Code und der returnUrl weitergeleitet, und die Sitzung wird erst nach Bestätigung des zweiten Faktors ausgestellt.

Welche Anbieter verfügbar sind, hängt von der Konfiguration deiner Organisation ab. Microsoft ist standardmäßig aktiviert; Google-Unterstützung existiert, ist aber standardmäßig deaktiviert.

Authentifizierungsfehler