Kapitel 4.3

API-Einstellungen

Unsere API findest Du unter https://thg.nxtlabs.online.

OAuth2 Clients verwalten

Um die API nutzen zu können, benötigst Du einen API-Schlüssel. Wir nutzen hierzu den OAuth2-Standard für Maschine-zu-Maschine Kommunikation mittels einer Client-ID und einem Client-Secret.

Du kannst Dir selbst OAuth2 Clients über das Kundenportal unter dem Bereich Kundenportal / API Settings erzeugen, diese temporär aktivieren und deaktivieren sowie löschen. Die OAuth2 Clients sind unbeschränkt nutzbar und laufen nicht ab.

Du kannst auch gerne mehrere Clients erzeugen, diese aktivieren und deaktivieren oder auch wieder löschen.

Speichere dir Client-ID und das Client Secret sobald du es erzeugt hast an einem sicheren Ort ab. Du wirst es im nächsten Schritt wieder brauchen. Übrigens, das Client Secret speichern wir selbst nicht und können es auch nicht rekonstruieren.

Hinweis: Ungenutzte OAuth2 Clients werden bei Inaktivität nach 4 Wochen aus Sicherheitsgründen deaktiviert und nach 12 Wochen gelöscht. Du kannst Dir aber jederzeit weitere OAuth2 Clients erzeugen, wenn Du wieder welche benötigst.

Token erzeugen

Mit einer aktiven Client-ID / Client-Secret Kombination kannst Du jederzeit ein Token erzeugen, welches für 24h gültig ist und mit welchem Du die freigeschalteten Dienste nutzen kannst. Spätestens dann musst Du Dir einfach ein neues Token erzeugen.

curl  -X POST https://hydra.nxtlabs.online/oauth2/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "scope=thg" \
      -u <client_id>:<client_secret>

Hinweis: Trage Deine persönliche Client-ID / Client-Secret Kombination anstelle von <client_id>:<client_secret> ein.

{"access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6ImI3MDZhZDM4LWExZGEtNGRmNC1iNmJiLWJjMWI3NDU3OGJlNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOltdLCJjbGllbnRfaWQiOiI3ODQ4MWYyMy0zNGYyLTQ2ZTctYWI1Zi00ZDFmMWQwOGViNzgiLCJleHAiOjE3NjU5NjUwMjMsImV4dCI6e30sImlhdCI6MTc2NTg3ODYyMywiaXNzIjoiaHR0cHM6Ly9oeWRyYS5ueHRsYWJzLm9ubGluZSIsImp0aSI6IjI1MmRhYTdkLWFmNTQtNDM1Yy1iNDcxLTFhZTZkNmMwMTNkYSIsIm5iZiI6MTc2NTg3ODYyMywic2NwIjpbInRoZyJdLCJzdWIiOiI3ODQ4MWYyMy0zNGYyLTQ2ZTctYWI1Zi00ZDFmMWQwOGViNzgifQ.I_BvD1hFm2uKYaq3N3ojpZ9djRhTEVnmRouRHoO8zRckfM6rDmrDPNzAnKgTOj-vMNBJAZEkvzqx0YOSQioCvbQYcBDdtCm-11mk-HbBrIgWbdbFQcMUHCQv7tyAdGHpDgNVWDC6kAvMoPw9A4eaHLoJk3ImBsizBGtTk1P9u-95XRbEBGlbHtKJxP_IZYSZun9i5T8gBP1cUxAuZFiqMdWYLmpxb7B3F5VQaEt7Es9TmduMTrmmAxMMYIWz7WEaxx2Aqc_5GDgA2_kLgJTAuFLsuuMD8GaW9LQfnQXCJbSppkRjrCe4pKfTP9pL12FqBdHU8RxG3V688B5foPAyFERiQTvBq5td-qp9sO0kHMX32uRJn-vyp6SjimjNjrjGnc0ySGzQi8i77IGMfmFkwD-GNPBq51c1-XLG5p-XVKFlkB2RZrslTT9krvHyfMRZYEU2SMYhmc0JUTUbZ5rxY4zzyvddxAySUCH1MoDWEIYHz6hVs1_LwTExRtrYI6Ki1PEKr3qechYKQQ2hCznADYZ_-28efcgVsE5foBLKUYFR8wIpOdycEGXt-a4kit5pGjFGGTypZ1oKdsihlGZbCksIIzX6HMzA8xm04FPVAyCtzcJGDFhyKlEfaJKuZiOqgEZBT4Z9Q6e-Mm-9H48pwDuur6oufL8TGo_Wd1tgAKg","expires_in":86399,"scope":"thg","token_type":"bearer"}

Hinweis: Es handelt sich hier nur um ein Beispiel für ein gültiges Token. Das eigentliche Token steht im Feld “access_token” und ist ein JWT.

Anfrage an API senden

Um eine Anfrage an eine unserer API-Endpunkte zu legitimieren, sendest Du das erzeugte Token im HTTP Authorization Header (Bearer <token…>) zusammen mit deiner Anfrage mit.

curl  -v https://thg.nxtlabs.online/api/v1/whoami \
      -H Authorization: Bearer <token>

Hinweis: Ersetze mit dem für Dich erzeugten Token.

Beispielantwort:

> GET /api/v1/whoami HTTP/2
> Host: thg.nxtlabs.online
> User-Agent: curl/8.5.0
> Accept: */*
> Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImI3MDZhZDM4LWExZGEtNGRmNC1iNmJiLWJjMWI3NDU3OGJlNiIsInR5cCI6IkpXVCJ9.eyJhdWQiOltdLCJjbGllbnRfaWQiOiI3ODQ4MWYyMy0zNGYyLTQ2ZTctYWI1Zi00ZDFmMWQwOGViNzgiLCJleHAiOjE3NjU5NjU1MjksImV4dCI6e30sImlhdCI6MTc2NTg3OTEyOSwiaXNzIjoiaHR0cHM6Ly9oeWRyYS5ueHRsYWJzLm9ubGluZSIsImp0aSI6IjhjNDI4MTIzLWRlNmQtNGQ5Ny1iZDM2LTExMDhiNmI0OGQ0OCIsIm5iZiI6MTc2NTg3OTEyOSwic2NwIjpbInRoZyJdLCJzdWIiOiI3ODQ4MWYyMy0zNGYyLTQ2ZTctYWI1Zi00ZDFmMWQwOGViNzgifQ.IBxOlhrN2OhAwEbugZTCO1JBF7R9WTCe5h_2wcrXreI_kyJoQ-ONIU-s5oFHiLBEcXI-wuVlxyZ3zKEHSWUe3LOworWmbmH4e8jpZl0laPjvmG1VH6VeJ_GOWbz_4M59cmQ65PL33xEIRUYwlmu6RDpedoVD3Biw-5ZIh3HvGteHi6m3f9Dzy7c6lNTNU6x3X9mCaVUem58UfKi6hl2Cr8T7TjeL2I5Ye3LIEFJx3WHRrhPcWRbo-0TKhaYqU5Cr2st8QaFaZanfgo_pGeVvfd5qZXQVQND9-MY5ddmjvxkuP46dDfOVgP0SKTBMGky8FsOO2yX7nQcbY60G-a4qd4ljrTPWy3bBwFJsxfYxtmnDVCFaRoZD4_P0uiumd4BhPa8ufgHXVRO2XVHxEfAaABffjXxSgK-Ir6WbZdVfbisigj4FkwHDdai8j9C0wDUe8NKAii9y6CcDpNbpjoybit3QLW-zo7uvuCVGb2EImqZQF0o6kIPEkc6laH78jFlITpoWm3EWb6Ad9RpyrOg45Iinivz4u2_XCZAuN_jdZVvboojjVJK-1Sp4HlEgxAWiEB012Tg8KdkhbPItfsXyMCAYuvsC5ThqsNqulk91nOxLOfhyAHuYxkORHiQSMnPthOuK7CVaE6d1wnYnKgI_EjMZvKP7O93MI3E7BveTSqc
> 
< HTTP/2 200 
< content-type: text/plain; charset=utf-8
< date: Tue, 16 Dec 2025 10:06:52 GMT
< content-length: 36
< 
* Connection #0 to host thg.nxtlabs.online left intact
78481f23-34f2-46e7-ab5f-4d1f1d08eb78

Well done! Du hast erfolgreich eine Anfrage an unsere API gestellt und eine gültige Antwort zurückerhalten (HTTP/2 200). Weitere technische Informationen zu den verfügbaren API-Endpunkten erhälst Du in unserer API-Dokumentation

Überprüfung eines Token mittels JWKS

Was ist ein JSON Web Key Set?

Bei den erzeugten Token handelt es sich um JSON Web Tokens (JWT) mit einer gültigen Signatur. Wir empfehlen zur Erhöhung der eigenen Sicherheit die Token-Signatur mittels des JSON Web Key Set (JWKS) zu überprüfen, den man über den Endpunkt JWKS herunterladen kann.

Achtung: Der JWKS wird aus Sicherheitsgründen unregelmäßig neu erstellt, sodass es ratsam ist, das JWKS dynamisch zu lesen und nicht lokal zu speichern.