Skip to content

API Authentication Using API Keys

HortiView supports access to its APIs via keys sent via X-Api-Key headers to support use cases that require machine-to-machine communication between the module's backend and HortiView. Examples use cases are:

  • Module backend retrieves farm definitions (fields, blocks, irrigation stations, etc.)
  • Module backend retrieves alert rule definitions to decide what to alert about and when
  • Module backend send alerts based on defined alert rules

Permissions

When publishing a module in HortiView you are able to specify data areas your module requires access to in order to function properly. API keys generated in HortiView will only work with data areas you have specified for your module. This mechanism ensures consistent authorization of data access independent of the channel used to access data. See our "Data Management Reference" for details.

Managing App Registrations

Important

The secret will be presented only once. You are responsible for storing it securely. You will not be able to retrieve the key again.

To register your module as an app please follow these steps:

  1. Login to your vendor account and select a module you want to register as an app.
  2. Navigate to tab "Dev Resources" and scroll to section "App Registrations".
  3. Create a new API key by clicking "Add App".
  4. Copy the secret API key right away in a secure location. It will not appear again once you leave the page.

Create API Key via API

It is possible to create your API key via an API call using the Bearer token:

curl -X 'POST' \
  'https://app.hortiview.com/api/v8.0/{vendorOrgId}/registerApiClient/{moduleId}' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -d ''

The response will contain the API key as the value for the clientSecret property:

{
  "moduleId": "04e1c98c-9e7e-416c-8422-0e84718a8864",
  "clientSecret": "MDRlMWM5OGMtOWU3ZS00MTZjLTg0MjItMGU4NDcxOGE4ODY0fE5kMnF6KHQ3ZnNjTkkhe0U=",
  "clientName": "ApiKey_eb6f51a9-9268-4bb3-aad8-ff41f31861cb",
  "parentId": "04e1c98c-9e7e-416c-8422-0e84718a8864",
  "clientId": "019cd2f0-9584-787c-9369-bc45bf11270d",
  "expiresOn": "2027-03-09T14:11:48.2500384+00:00",
  "id": "eb6f51a9-9268-4bb3-aad8-ff41f31861cb"
}

Using API Key

On each request send the secret as an X-Api-Key header. For example, to query the farm definitions of organizations your module is installed in, use the following call semantic:

curl -X 'GET' \
  'https://app.hortiview.com/api/v8.0/Alerts/StructuresByModuleId/{moduleId}' \
  -H 'accept: text/plain' \
  -H 'X-Api-Key: {clientSecret}'