OAuth

Für alle API Zugriffe wird eine Benutzer OAuth Access Token benötigt. TimberData bietet dafür eine OAuth 2.0 Schnittstelle an. Um diese Schnittstelle nutzen zu können nehmen Sie bitte Kontakt mit uns auf. Wir Erstellen dann eine Client ID für Sie. Ohne diese Client ID kann der prozess nicht genutzt werden.

Aus Sicherheitsgründen muss auch die Redirect URL die für den Prozess verwendet wird uns genannt werden und der Prozess wird auch nur mit dieser URL funktionieren.

Eine detailierte Spezifikation zu OAuth 2.0 ist hier zu finden: RFC-6749

Starten des OAuth Authorisierungs Prozess

Wenn Sie eine Client ID haben können Sie User zum Start des Prozesses weiterleiten auf: https://app.timberdata.de/auth?response_type=code&client_id=<CLIENT ID>&redirect_uri=<REDIRECT URL>&scope=<SCOPES>[&state=<STATE>]

Der User hat dort die Möglichkeit sich anzumelden und danach den Zugriff Ihrer Anwendung auf TimberData zu bestätigen.

Erläuterung der Parameter

• <CLIENT ID> muss ersetzt werden mit der von uns gegebenen ID
• <REDIRECT URL> muss ersetzt werden mit einer von Ihnen bei der Abstimmung der Schnittstelle genannten URLs
• <SCOPES> ist streng genommen Optional. Ohne jeglichen Scope können Sie allerdings nur die Basis-Informationen des Benutezrs lesen. Eine Liste aller verfügbaren Scopes finden Sie weiter unten auf dieser Seite.
• <STATE> ist optional. Dieser Wert wird unverändert von uns an die Weiterleitung angehangen mit dem der Benutzer zurück zu Ihrer Anwendung kommt. Um Sie sich gegen Cross-site Angriff zu schützen bei denen Angreifer eigene Codes verwenden empfehlen wir diesen Parameter zu nutzen.

Wenn der User den Zugriff bestätigt hat wird er auf die angegebene redirect_uriURL weitergeleitet mit den query Parameter code. Also beispielsweise wenn redirect_uri=https%3A%2F%2Fbeispiel-seite.de%2Fconnect%2Ftd dann könnte die Weiterleitung https://beispiel-seite.de/connect/td?code=ABC123 sein. Mit diesem Code können sie dann einen Access Token genereieren. Bitte beachten Sie, dass der Code eine kurze Gültigkeit ( max 10 Minuten ) hat und nur einmalig verwendet werden kann.

Um den Access Token zu generieren rufen sie folgende URL von ihrem Server aus auf:

https://api.timberdata.de/oauth/v1/token?code=<CODE>&grant_type=authorization_code
	&redirect_uri=<REDIRECT_URL>&client_id=<CLIENT ID>&client_secret=<CLIENT_SECRET>

Hierauf bekommen Sie eine Antwort inklusive Access Token.
Dieser Endpunkt akzeptiert auch form data wenn diese als POST Request übermittelt werden. Client ID und Secret können auch als Benutzername und Passwort für eine Basic Authentifierung genutzt werden. In diesem Fall kann der client_secret Parameter bei der Anfrage entfallen.

Beispiel Antwort:

{
	"access_token": "eyJhbGciOi[...]",
	"token_type": "Bearer",
	"expires_in": 31104000,
	"scope": "aggregation woodlist"
}

Verwendung des Access Token

Der Access Token sollte bei jeder Anfrage an die API als Authorization HTTP Header in folgedem Format mitgegeben werden: Bearer <TOKEN>

Beispiel:

curl --request GET \
  --url https://api.timberdata.de/inventory/v4/user \
  --header 'Authorization: Bearer eyJhbGciOi[...]'

Scopes

• Ohne jeglichen Scope ist nur der Zugriff auf der User Endpunkt möglich.
• aggregation - Ermöglicht das Lesen von Poltern des User.
• woodlist - Ermöglicht das Lesen von Holzlisten.

Wenn Sie auf mehr als eine Resource Zugriff haben müssen verbinden Sie Scopes bei der Authentifierungs Anfrage mit einem Leerzeichen. Also z.B. &scope=aggregation woodlist.