Auth API

Die Auth API ist ein OAuth-Ablauf, der einen ServiceUser (einen regulären Endnutzer des Produkts, das ein Space betreibt) per Social Login authentifiziert. Nach der Anmeldung über den in der ServiceLogin-Konfiguration hinterlegten Anbieter (z. B. Google) stellt diese API einen accessToken und einen refreshToken aus. Der ausgestellte accessToken ist ein Bearer-Token, das ausschließlich für ACMA- und ACDA-Aufrufe verwendet wird, und kann nicht für CMA oder CDA eingesetzt werden. Kein Token überschreitet die Identitätsgrenze.

Die Basis-URL ist https://auth.weegloo.com/v1, und alle Pfade liegen unterhalb von /spaces/{spaceId}/.... Alle Anfrage- und Antwortbodys sind JSON. Für Browser-Anwendungen wird empfohlen, diese HTTP-Anfragen und -Antworten nicht selbst zu behandeln, sondern das offizielle SDK weegloo-service-user zu verwenden. Diese Seite behandelt das Format der HTTP-Anfragen und -Antworten, die dieses SDK intern aufruft. Ziehen Sie sie heran, wenn Sie den Ablauf in Umgebungen ohne SDK (Server, Native, Skripte) selbst implementieren.

Anmeldeablauf

Der folgende Anmeldeablauf bezieht sich auf Browser-Anwendungen. Bei nativen Apps (Android und iOS) läuft die Callback-Verarbeitung anders ab; sie wird gesondert unter Native-App-Callback: Deep-Link-Brücke behandelt.

Die Anmeldung läuft in vier Schritten ab.

1. Leiten Sie den Browser zur Anmelde-Einstiegs-URL (/spaces/{spaceId}/login/oauth2/{provider}). Diese URL startet eine Redirect-Kette, die zum Anmeldebildschirm des Anbieters (Google) führt.
2. Nach abgeschlossener Anmeldung schickt Weegloo den Browser an die in ServiceLogin konfigurierte callbackUrl zurück und hängt ?exchangeToken=<einmaliges Token> an die Adresse an.
3. Die Callback-Seite liest den exchangeToken aus der Adresse, sendet ihn an den Token-Austausch-Endpunkt (POST /spaces/{spaceId}/oauth/token) und erhält als Antwort einen accessToken und einen refreshToken.
4. Anschließend rufen Sie ACMA und ACDA mit dem accessToken als Bearer-Token auf. Erneuern Sie ihn vor Ablauf (expiresAt) mit dem refreshToken und widerrufen Sie das Token beim Abmelden.

Der exchangeToken ist einmalig verwendbar. Entfernen Sie ihn unmittelbar nach der Verarbeitung des Callbacks aus der Adressleiste, um Offenlegung und Wiederverwendung zu verhindern (bei Verwendung des SDK geschieht dies automatisch).

Native-App-Callback: Deep-Link-Brücke

Auch native Apps für Android und iOS melden sich über denselben OAuth-Ablauf an. Allerdings kann als callbackUrl nur eine Webadresse eingetragen werden, weshalb die Anbindung anders verläuft.

Die laut Dokumentation unterstützte callbackUrl ist eine Webadresse wie https://.... Ein von der App registriertes benutzerdefiniertes Schema wie myapp:// wird abgelehnt und kann daher nicht direkt als Callback-Adresse verwendet werden. Deshalb legen native Apps als callbackUrl eine https-Brückenseite fest, die über Web Hosting bereitgestellt wird, und diese Seite reicht den im Callback enthaltenen ?exchangeToken=... an den Deep Link der App (z. B. myapp://auth/callback?exchangeToken=...) weiter. Die App führt den Token-Austausch (Schritt 3 des obigen Anmeldeablaufs, POST /spaces/{spaceId}/oauth/token) mit diesem exchangeToken selbst durch.

• Über den Deep Link wird nur der einmalig verwendbare exchangeToken übergeben. accessToken und refreshToken tauscht die App selbst ein und erhält sie direkt, sie laufen also nicht über den Deep Link. Auch die Brückenseite entfernt den exchangeToken aus der Adresse, nachdem sie den Wert weitergereicht hat (dasselbe Prinzip wie beim Callback des Anmeldeablaufs).
• Verwenden Sie nach Möglichkeit verifizierte Deep Links (Android App Links, iOS Universal Links). Ein nicht verifiziertes benutzerdefiniertes Schema kann von einer anderen auf dem Gerät installierten App abgefangen werden.
• Der OAuth-Client des Anbieters (z. B. Google) wird auch bei einer nativen App als Typ Web application erstellt. Denn die OAuth-Weiterleitung führt nicht zur App, sondern zu auth.weegloo.com (einer Webadresse).

Wie Sie die Brückenseite bereitstellen, wird unter Web Hosting behandelt.

Token-Modell

Token-Austausch und Erneuerung liefern eine Token-Antwort derselben Form zurück. Die in der Antwort enthaltenen Token-Strings und Zeitpunkte entsprechen den folgenden Beispielwerten, sind in der Realität jedoch undurchsichtige Geheim-Strings (da der Ablauf eine Anbieter-Anmeldung durchläuft, lassen sich die tatsächlichen Werte nicht unverändert übernehmen).

{
  "accessToken": "QY3xK9pR2mLs7Vc0Zt8Nf4Wd1Bj6Hg5Ua2Ee9Ck3PoZt8Nf4Wd",
  "tokenType": "Bearer",
  "scope": ["APP"],
  "createdAt": "2026-06-18T05:00:00.000Z",
  "expiresAt": "2026-06-19T05:00:00.000Z",
  "refreshToken": "Rf7Hn2Qw9Zx4Tp1Lk6Vc3Bm8Yd5Gs0Ae2Uj7Co4NeLk6Vc3Bm",
  "refreshExpiresAt": "2026-06-21T05:00:00.000Z"
}

Die Lebensdauer der drei Token ist wie folgt.

• Der exchangeToken ist einmalig verwendbar und kurzlebig. Er muss unmittelbar nach dem Callback eingetauscht werden. Er ist nicht in der Austausch-Antwort enthalten, sondern wird in Schritt 2 des Anmeldeablaufs über die Adresse übergeben.
• Die Lebensdauer des accessToken ist kein fester Wert. Der genaue Ablaufzeitpunkt steht in der Antwort unter expiresAt, richten Sie sich daher nach diesem Wert. Er ist ausschließlich für ACMA und ACDA bestimmt.
• Der refreshToken ist nach der Ausstellung drei Tage lang gültig (refreshExpiresAt). Beim Aufruf der Erneuerung wird ein neues Paar aus accessToken und refreshToken ausgestellt und das vorherige Paar widerrufen (Rotation). Bei jeder Erneuerung ist der unmittelbar vorhergehende refreshToken nicht mehr verwendbar.

API

Die Basis-URL der vier nachstehenden Endpunkte ist jeweils https://auth.weegloo.com/v1. Behandelt werden sie in der Reihenfolge: Anmelde-Einstieg (GET), Token-Austausch (POST), Token-Erneuerung (POST), Abmeldung (DELETE).

Verwandte Dokumente

• ServiceUser-Anmeldung (Konzept): Wie ServiceLogin im Content-Studio konfiguriert wird.
• ACMA: Die API, um mit dem ausgestellten Token Mitglieder-Content zu verwalten.
• ACDA: Die Lese-API, die an Mitglieder ausgeliefert wird.