A third party application can only access data of an installation after the farmer has given its permission. If the farmer gives permission you will receive a token that will allow you to authenticate to the Nedap Livestock Connect API. Each time you make an API call you need to present this token as a proof of permission.

For this authorization and authentication process, we make use of the standard OAuth2 authorization protocol. More information about the OAuth2 authorization protocol can be found here.

Implementing OAuth2 protocol

To set up a scalable infrastructure which can handle the authorization process you need to implement the OAuth2 protocol in your application. This requires your application to have an interface for the farmer and a dedicated server to accept requests and store tokens.

Prepare

To use the OAuth2 authorization protocol to get authorization from farmers, the first step is to write some code in your application that can redirect the farmer to a Nedap page where he can authorize your application to access data of his installation. This requires some work to implement, but once built it is a safe scalable solution which makes it easy for new farmers to connect your application to his Nedap Livestock installation.

OAuth2 flow summarized:

  • 1. Your application redirects the farmer to the Business Insight dialog.
  • 2. The farmer can log in with his Business Insight credentials (for more information see Business Insight) and can authorize your application.
  • 3. The farmer is redirected to your application and includes a temporary authorization token.
  • 4. You retrieve the permanent access token from the API using this authorization token.

Step 1: Redirect the Farmer to the Business Insight dialog

Initialize the authorization process by redirecting the farmer from your own application to the Business Insight dialog. You should include your own client id (which you have received from Nedap), and a callback URL.

Example:

curl -H GET https://nedap-bi.com/oauth/authorize \
-d 'client_id=0855df3868'\
-d 'redirect_uri=https://my_application.com/authorization_code'\
-d 'response_type=code'\

Step 2: Farmer authorizes your application

[hier komen 2 screenshots van BI-gebruiker die toegang geeft]

Step 3: Farmer is redirected to your application and provides you an authorization token

The Farmer is redirected to your callback URL provided in the request. If the user authorized your application the redirection URL contains an additional parameter, the authentication token. For the code example above, a successful authorization process will result in calling the following URL: https://my_application.com/authorization_code?code=aecd3e40cd

Step 4: Retrieve access token

With the received authorization token, you can request an access token from the authorization server. In the request you have to include your private client id and client secret (which you have received from Nedap), a callback URL and the received authorization token.

Example Authorization token:

curl -d 'client_id=0855df3868'\
-d 'client_secret=b0147b284a'\
-d 'code=aecd3e40cd'\
-d 'grant_type=authorization_code'\
-d 'redirect_uri=https://my_application.com/access_code'\
https://nedap-bi.com/oauth/token

Access token and refresh token

If everything went ok, the authorization server returns an access token and a refresh token. For example:

{
"access_token": "14f47b4ceb",
"token_type": "bearer",
"expires_in": 6464,
"refresh_token": "dfea2eccfd",
"scope": "account"
}

API calls header

With this access token you can access the data of the corresponding installation by adding the following header to the API calls:

'Authorization': Bearer 14f47b4ceb

[hier komt nog ‘List of OAuth methods’. Evt. als te downloaden document weergeven]