API-Authentifizierung

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

Der API-Zugang ist im Agent-Preis enthalten und verursacht keine zusätzlichen Kosten.

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). Beide sind opake Zeichenketten, die octoja ausstellt — speichere sie genau so, wie du sie erhältst, und schicke sie unverändert zurück. Jede erfolgreiche Anmeldung, auch über die API, setzt zusätzlich das Session-Cookie octo_session, das die octoja-Weboberfläche verwendet.

Login

POST /api/auth/login

Request Body

Beispiel-Request

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

Erfolgreiche Antwort

{ "tokenType": "Bearer", "accessToken": "<access_token>", "expiresIn": 3600, "refreshToken": "<refresh_token>" }

Refresh

POST /api/auth/refresh

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

Standardmäßig gilt ein Access-Token eine Stunde und ein Refresh-Token 14 Tage ab seiner Ausstellung. Verwende expiresIn aus der Antwort für die Lebensdauer des Access-Tokens.

Ein erfolgreicher Refresh stellt ein neues Token-Paar mit neuen Laufzeiten aus. Speichere beide neuen Token und verwende sie für weitere Anfragen. Ist das Refresh-Token abgelaufen, musst du den Login-Ablauf erneut durchlaufen.

Request Body

Beispiel-Request

{ "refreshToken": "<refresh_token>" }

Erfolgreiche Antwort

{ "tokenType": "Bearer", "accessToken": "<access_token>", "expiresIn": 3600, "refreshToken": "<refresh_token>" }

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

octoja unterstützt Single Sign-On über OIDC-Anbieter wie Microsoft — sowohl aus dem Browser als auch aus einer nativen App.

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.

Browser-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 SSO-Anbieter für deine octoja-Instanz eingerichtet sind, legt der octoja-Support fest. Mitglieder einer Administratorgruppe können bereits eingerichtete Anbieter unter Einstellungen → Authentifizierung im Bereich SSO-Anbieter aus- und wieder einschalten. Fehlt dort ein gewünschter Anbieter wie Google, kontaktiere den octoja-Support und nenne die URL deiner octoja-Instanz.

Login aus einer nativen App

Eine native App durchläuft denselben Ablauf mit PKCE, sodass das einmalige Ergebnis an die App selbst geht und nicht an den System-Browser.

1. Rufe GET /api/auth/oidc/{provider}/authorize?returnUrl=<your-callback-uri>&codeChallenge=<pkce_code_challenge> auf. Verwende als returnUrl genau die Callback-URI, die unser Support für dich freigeschaltet hat.
2. Öffne die zurückgegebene URL im System-Browser, damit sich der Benutzer beim Anbieter anmelden kann.
3. Der Callback leitet den Browser an deine Callback-URI weiter, mit einem einmaligen handoff-Code im Query-String.
4. Löse diesen Code aus der App heraus mit POST /api/auth/oidc/handoff ein und übergib dabei den PKCE-Verifier, der zur Challenge aus Schritt 1 passt: { "handoff": "<handoff_code>", "codeVerifier": "<pkce_code_verifier>" }. Die Antwort enthält dasselbe Token-Paar wie ein Passwort-Login.
5. Ist für den Benutzer die Zwei-Faktor-Authentifizierung aktiviert, antwortet der Handoff-Aufruf mit 403 Forbidden und der Code bleibt gültig — wiederhole dieselbe Anfrage und ergänze den Einmalcode des Benutzers.

Authentifizierungsfehler