OAuth

It is nessesary to include an access token for nearly all API calls. TimberData provides OAuth 2.0 for external services to get access to a users information. To use OAuth 2.0 with TimberData pleasse get in contact and we will set up a client ID. Without a client ID and configured redirect URI this process cannot be used. For security purpose all redirect URIs must be configured on our end so please tell us the redirect URIs you will use.

The full OAuth 2.0 spec can be found here: RFC-6749

Start the auth process

With the client ID we provide you build a URL and redirect users to it. The URL format is: https://app.timberdata.de/auth?response_type=code&client_id=<CLIENT ID>&redirect_uri=<REDIRECT URL>&scope=<SCOPES>[&state=<STATE>]

The user will need to log in on that page if not already logged in to TimberData and then grant your application access to the requested data.

Auth URL Query parameters

  • <CLIENT ID> replace this with the client ID we provide you
  • <REDIRECT URL> must be replaced with a configured redirect URL for your client ID
  • <SCOPES> technically optional but without any scope you will only be able to read basic user information.
  • <STATE> optional but to secure yourself from cross-site attacks we recommend sending a state and checking any requests coming back. We will send any state given unchanged back with the redirect back to your application.

If the user grants ( or denies ) access they will be redirected back via the redirect URI provided. If access has been granted the URL will include the code query parameter. With a given redirect_uri=https%3A%2F%2Fexample.com%2Fconnect%2Ftd this would look like https://example.com/connect/td?code=ABC123. This code can be used to get a access token. Note that the code is only valid for one use and expires within 10 minutes after the user is redirected back to your application.

To get the final access token use this code and make a request from your server to the following endpoint:

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>

Client ID, Redirect URI must be identical to the original auth redirect to us.
This endpoint also accepts form data when transmitted via POST method. client ID and secret can also be used to create a basic authentification. In that case the client_secret parameter should not be transmitted in the payload.

Example Response:

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

How to use the access token

The access token should be included in the Authorization HTTP Header in every following request. The format for header value is: Bearer <TOKEN>.

Example call:

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

Scopes

  • Without any scope you only have access to the user endpoint.
  • aggregation - Allows access to read aggregations.
  • woodlist - Allows you to read woodlists.

If you want to request access to multiple scopes just combine the strings in the URL with a space. E.g. &scope=aggregation woodlist.