A third party application can only access data of an installation after the farmer has given its permission. If the farmer gives permission your application will receive a token that will allow it 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 that can handle the authorization process you need to implement the OAuth2 protocol in your application. The OAuth2 protocol requires you to build a link in your web application that can redirect the farmer to the Nedap Business Insight page where he/she can safely login and grant permission to your application to access their Nedap Livestock solution. Once built, the OAuth2 protocol is a safe scalable solution that makes your Nedap connection available to all farmers who are using your application and a Nedap solution in an easy way.

OAuth2 flow summarized:

Step 1: Your application redirects the farmer to the Nedap Business Insight dialog.

Step 2:  The farmer can log in with his Business Insight credentials and can authorize your application.

Step 3:  The farmer is redirected to your application and includes a temporary authorization token.

Step 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 Nedap Business Insight dialog. You should include your own Client ID (which you have received from Nedap), and a callback URL.

Code example:

https://nedap-bi.com/oauth/authorize?client_id=0855df3868&redirect_uri=https://my_application.com/authorization_code&response_type=code

If you want to request access with more permissions than the default one, you should provide the scopes (the permissions) you want access to. The default scope is 'account', which will be used when no scopes are provided.

A code example that provides more scopes:

https://nedap-bi.com/oauth/authorize?client_id=0855df3868&redirect_uri=https://my_application.com/authorization_code&response_type=code&scope=account+sorting

Step 2: Farmer authorizes your application

The farmer is redirected to the Nedap Business Insight page where he can login with his Business Insight account and can authorize your application. For more information, check the Get farmers’ permission page.

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:

Successful redirection:

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.

Code Example:

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

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

Successful authorization response:

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

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

Authorization header:

'Authorization': Bearer 14f47b4ceb

Revoke token

If you ever wish to revoke a token, this can be done with the following call:

curl -F client_id=0855df3868 \
-F client_secret=0d74dkfi3 \
-F token=aecd3e40cd \
-X POST https://nedap-bi.com/oauth/revoke