Authentication

Every request to the AgriWebb API is authenticated with one of two credentials.

With an access token:

curl https://api.agriwebb.com/v2 \
  --header 'Authorization: Bearer {access token}' \
  --header 'Content-Type: application/json' \
  --data '{"query": "{ farms { id name } }"}'

With an API key:

curl https://api.agriwebb.com/v2 \
  --header 'x-api-key: {API key}' \
  --header 'Content-Type: application/json' \
  --data '{"query": "{ farms { id name } }"}'

The Marketplace Callback accepts an access token only.

Credentials are issued per environment, and only work against that environment's base URLs. See Environments.

OAuth 2.0 credentialsCopy Anchor Link

The OAuth 2.0 flow uses other credentials to obtain an access token.

Authorisation codes expire after 10 minutes, access tokens after 12 hours and refresh tokens after 28 days. The token exchange response gives the access token's lifetime in seconds as expires_in: use it rather than assuming 12 hours. See Refreshing an expired access token.

Authorisation codes and refresh tokens are single use. Every token exchange returns a new refresh token, valid for another 28 days, and revokes the one it was given, so store the new one each time. An integration that refreshes at least every 28 days keeps its access; once its refresh token expires, the user has to install it again.

Two behaviours tolerate a mistaken retry. Relying on either is an anti-pattern:

• A refresh token presented again within its grace period (one minute by default) returns the same tokens as its first exchange. The grace period lets you recover a lost response. Don't use it to share one refresh token between processes.
• Exchanging the same code or refresh token twice at the same time can succeed both times, with different tokens each time. Exchange each code and refresh token once, from one process.

If you present a used code, or a refresh token after its grace period, AgriWebb revokes every token issued to the integration and the user has to install it again.

Token exchanges for the same integration issue their tokens one at a time. An exchange made while another is in progress waits for it to finish, and returns 429 if it cannot start within about 15 seconds. Each exchange checks its code or refresh token before it waits, so two exchanges of the same code or refresh token made at the same time can both succeed. Concurrent exchanges are an anti-pattern: make a best effort to perform an integration's token exchanges synchronously, starting each one only once the previous one has finished.

Scopes and accessCopy Anchor Link

A credential grants a set of scopes and access to specific farms and organisations. A request fails unless the credential has the scope the operation requires and access to the farm or organisation it names.

The following scopes are available. The *-reports scopes are for the Reports API, and the rest for the GraphQL API. A write: scope does not grant read access: request the matching read: scope as well. Each query and mutation in the GraphQL reference lists the scope it requires, and each report's page under Reports lists the scopes it requires.

• read:farms
• write:farms
• read:records
• write:records
• read:sessions
• write:sessions
• read:fields
• write:fields
• read:feed-on-offers
• write:feed-on-offers
• read:feed-on-offer-targets
• write:feed-on-offer-targets
• read:pasture-growth-rates
• write:pasture-growth-rates
• read:rainfalls
• write:rainfalls
• read:map-features
• write:map-features
• read:level-readings
• write:level-readings
• read:management-groups
• write:management-groups
• read:enterprise
• write:enterprise
• read:animals
• write:animals
• read:animal-reports
• read:paddock-reports
• read:inventory-reports