API Zugriff

Just Social verfügt über eine Public API, in der bestimmte Endpunkte aufgerufen werden. Sie wird in den nächsten Jahren erweitert werden. Die Berechtigungen für den Zugriff können in der Admin App unter "Anbindungen -> Public API" in Just Social freigegeben werden. Sofern der Punkt auf eurer Plattform noch nicht vorhanden ist, meldet euch bitte bei uns.

Über den Aufruf der folgenden URL

https://<Just-Platform>/public-api/swagger-ui/index.html

findet ihr die generelle als auch Endpunkt-spezifische öffentliche Dokumentation. Dazu müsst ihr euch aber zuvor in Just Social mit einem gültigen Account eingeloggt haben.

Dort findet ihr Informationen zu

• den verfügbaren Endpunkten
• der Art der bereitgestellten Daten
• Art und Weise des Logins
• den benötigten Scopes

Es ist möglich, mehrere Clients zu definieren, die jeweils nur für bestimmte Scopes Zugriff erhalten. Ihr könnt aber auch einem Client Zugriff zu mehreren Scopes geben.

Sofern ihr die Just Accounts als Login für andere Systeme nutzen wollt, wird euch das Kapitel unten weiterhelfen.

Login mit Just

Ihr könnt Just Social verwenden um für andere Anwendungen den Login zu übernehmen.

Just Social implementiert den OAuth Authorization Code Flow (siehe auth0 Docs) und agiert als Authorization Server.

Um einen externen Client zu registrieren müsst ihr euch an den Support wenden und uns eine redirect_uri mitteilen.

Ihr erhaltet von uns dann über einen verschlüsselten Kanal eine client_id, ein client_secret und zur Überprüfung für euch, dass wir nicht falsch copy&pasted haben, die redirect_uri, die wir in der Datenbank gespeichert haben.

Achtung: Diese Daten sind nur einmalig abrufbar! Bitte auch die redirect_uri zu Troubleshooting Zwecken speichern.

Damit könnt ihr euch dann wie folgt gegen eure Just Social Instanz authentifizieren:

1. GET https://${DEINE-JUST-SOCIAL-URL}/auth/oauth2/authorize?response_type=code&client_id=${CLIENT_ID}&state=${RANDOM_NONCE}&scope=api&redirect_uri=${YOUR_REDIRECT_TARGET}">https://${YOUR_JUST}/auth/oauth2/authorize?response_type=code&client_id=${CLIENT_ID}&state=${RANDOM_NONCE}&scope=api&redirect_uri=${YOUR_REDIRECT_TARGET}

   Hinweis: ${YOUR_REDIRECT_TARGET} muss die exakte Url sein, die ihr uns zu beginn mitgeteilt habt!
   
   

2. Euer Server bekommt dann nach erfolgreicher Authentifizierung des Users folgenden Request zurück:

   GET ${YOUR_REDIRECT_TARGET}?code=${AUTH_CODE}&state=${NONCE}

3. POST https://${YOUR_JUST}/auth/oauth2/token

   mit folgenden Werten als application/x-www-form-urlencoded im Body:

   code=${AUTH_CODE}
   redirect_uri=${YOUR_REDIRECT_TARGET}
   client_id=${CLIENT_ID}
   client_secret=${CLIENT_SECRET}

   Als Antwort erhaltet ihr ein JSON Objekt mit folgendem Inhalt
   

   {
     "access_token":"${TOKEN}", // opaque/reference token
     "token_type":"bearer",
     "expires_in":nnn,
     "scope":"api"
   }

Der erhaltene access_token, kann nun in nachfolgenden API Requests als Bearer Token im Authorization Header verwendet werden.

Die Basisdaten des eingeloggten Users können als JSON über den folgenden Endpunkt geladen werden:

GET https://${YOUR_JUST}/toro/api/v1/person/current

⚠ Achtung: Der access_token ist nicht scoped und erlaubt einer 3rd Party Anwendung vollen Zugriff auf die API Methoden der eigenen Just Social Plattform im Authorisierungskontext des eingeloggten Users.

Aufgrund hoher Nachfrage prüfen wir aktuell die Entwicklung einer Lösung zur reinen Authentifizierung mit Just Social als Identity Provider und Identity Tokens, die im Nachgang keinen API Zugriff ermöglichen.

Troubleshooting

400 - invalid_grant: Bitte prüft genau, ob ${YOUR_REDIRECT_TARGET} exakt mit dem String übereinstimmt, den ihr am Anfang als redirect_uri an unseren Support kommuniziert habt.

401 - invalid_client/Bad client credentials: client_secret und/oder client_id sind falsch, oder der Request Body ist falsch formatiert. Überprüfe die Credentials, stelle sicher, dass der Body application/x-www-form-urlencoded ist, 
also wie ein Query String aussieht:"code=...&redirect_uri=http%3A%2F%2Flocalhost...".
Wir empfehlen Postman zum Testen. Über die Konsole kann man genau sehen wie die Daten formattiert sind, die hin- und hergehen.

Haftung & Support

Für Anbindungen/Integrationen von Drittsoftware an/in Just Social übernimmt Just Software keine Haftung und leistet keinen Support. Die hier gelisteten Methoden sind nicht stabil und können in der Zukunft Breaking Changes unterliegen, so dass die Anbindungen/Integrationen nicht mehr funktionieren.