Create a new Croplet.  After giving our approval, your application will be available on the apps page.
When you create your Croplet, you can specify which permissions you need. When a user wants to install your Croplet on their farm, the requested rights will be presented. The user can than decide weather to install or not to install your Croplet.

When registering your Croplet you can fill in the following options:

Name	Users see this name in the apps page.
Url	The url of the page you want to display in your Croplet, this is the page the user see when he/she clicks on your Croplet, when it's installed on his/her farm. e.g. https://www.example.com/
Callback Url	This url is used for the OAuth authentication. Our Dacom platform will call this URL to provide you with the access token. e.g. https://www.example.com/callback/ You also need this callback url when requesting an OAuth token. We will use this url to verify your OAuth request and it should be exactly the same.
Gid	This is a Dacom platform unique id for your Croplet.
Description	A short description of what your Croplet does. It displayed to the user when he want to install your Croplet on his/her farm.
Pictogram	An image url, this image is used to display your Croplet in our apps page. If not provided a default image of the given name will be used.
Place in store	If checked and your Croplet was approved, the Croplet will be listed on the apps page.

On the oauth2 client overview page you can see your generated Clients. A Client contains the automatically generated credentials needed to retrieve authorization from Dacom users. It is important that you keep the client_id and client_secret secure, and never expose it to anyone! You may only use the credentials in a secure connection, never in Ajax calls or store it in a native application (mobile).

Never share your credentials with anyone.

To retrieve Dacom data from a user, you will need a way to authenticate as them. This is done with an access token, it is an unique code specifically for your Client. This is how you generate an access token for a user for your application:

1. Get an authorization_code with your client_id

Your Croplet needs to get authorization from a Dacom user, to access this users data. This is done with an authorization_code. To get an authorization_code the user need to give permissions that your croplet may access his data. By specifying your client_id and the correct response_type the user will be able to authorize or deny your request:

GET https://dacom.farm/oauth2/authorize/?response_type=code&client_id=client_id

The Dacom user will now be prompted to log in to Dacom (if he is not already). After that a page will show up where the user will be able to confirm or deny your request to access his information. When the user confirms, an authorization_code will be sent back to your application (via the Callback url you used to register your Croplet):

GET https://callback_url/?code=authorization_code

In your application you will have to implement a routine on this callback url that retrieves the authorization_code and uses it for the next step.

TIP: see also the code example mentioned in the introduction

2. Use the authorization_code to retrieve an access token

You are now ready to retrieve an access token of the Dacom user for your application. You will need your authorization_code, client_id, client_secret and callback_url to do the following request:

                POST https://dacom.farm/oauth2/token/
                {
                    "grant_type":"authorization_code",
                    "code":authorization_code,
                    "client_id":client_id,
                    "client_secret":client_secret,
                    "redirect_uri":callback_url,
                }
            

If everything is correct you will receive the following response:

                HTTP/1.1 200 OK
                Content-Type: application/json;charset=UTF-8
                Cache-Control: no-store
                Pragma: no-cache
                {
                    "access_token": "eUMA45tjyKeLGPgonTfmCv5cuegtyy",
                    "token_type": "Bearer",
                    "expires_in": 3600,
                    "refresh_token": "MT6BDBca8NrhCuduOeQsJ2RW8e6gLM",
                    "scope": "crop_f:read"}
                }
            

The response contains the access token of the user. With this access token it is possible to retrieve the user's Dacom data on the API.
Like your Client credentials, it is important that you keep this code out of the hands of everyone who is not your user. The response also contains a expires_in, this value says how long (in seconds) this access token is valid, in the above example the access token if valid for 1 hour (3600 sec.). Once it in expires the access token can't be used anymore.

3. Use the refresh_token to get a new access token

Once an access token expires it can't be used anymore. If it is used the API will respond with an 401 error response. You need to refresh the access token to retrieve a new valid token.

                POST https://dacom.farm/oauth2/token/
                {
                    "grant_type":"refresh_token",
                    "refresh_token":refresh_token,
                }
            

If everything is correct you will receive the following response:

                HTTP/1.1 200 OK
                Content-Type: application/json;charset=UTF-8
                Cache-Control: no-store
                Pragma: no-cache
                {
                    "access_token": "8XFDJx4A46g4ybvX8m5N6H6Ch8rOEi",
                    "token_type": "Bearer",
                    "expires_in": 3600,
                    "refresh_token": "mfYzPH8cwb9dzUralik5jkYKLZUXqX",
                    "scope": "crop_f:read "
                }
            

The response is the same as when you retrieve an access token, but the access_token and refresh_token contain new values.

TIP: see also the code example mentioned in the introduction

While requesting data from our API, you will need to sign your requests with an Authorization header containing the access token of the user your wish to retrieve data from. A request might look similar to this:

GET https://dacom.farm/api/v3/farms/{farm_id}/

The access token must be present in the request headers like:

Authorization: Bearer access token

See the API docs for more information on the API. Only use the access token when using a encrypted connection

Error handling

When you use an invalid token the API will respond with an HTTP 401 code. In this cause you need to retrieve or refresh an access token.