Integration Guide

The AgriWebb Marketplace supports the OAuth 2.0 Authorisation Code Grant. This integration guide steps through how a server can integrate with the AgriWebb Marketplace. We have a sample app that implements this flow which you can see on GitHub.

Environments & Endpoints

All Partners will be required to build their integration behind a feature flag. Once the integration is finalised and tested, we will follow the agreed upon production release plan.

Staging

Base URL	https://auth.staging.agriwebb.com/
Name	Method	Path
Authorisation Request	POST	/oauth2/authorize
Token Exchange	POST	/oauth2/token
OAuth 2.0 Metadata	GET	/.well-known/oauth-authorization-server
Base URL	https://api.staging.agriwebb.com/
Name	Method	Path
GraphQL	POST	/v2
Marketplace Callback	POST	/v2/marketplace/callback

Production

Base URL	https://auth.agriwebb.com/
Name	Method	Path
Authorisation Request	POST	/oauth2/authorize
Token Exchange	POST	/oauth2/token
OAuth 2.0 Metadata	GET	/.well-known/oauth-authorization-server
Base URL	https://api.agriwebb.com/
Name	Method	Path
GraphQL	POST	/v2
Marketplace Callback	POST	/v2/marketplace/callback

OAuth 2.0 Flow

When a user selects to install an integration from the AgriWebb Marketplace, we will initiate the authorisation flow with the nominated Partner. AgriWebb uses OAuth 2.0 Authorization Code Grant to grant access tokens to Partners.

Step 1 - Install

Please see the Partner API Reference - Install Endpoint for technical specifications.

Partner Endpoint Implementation Required

Once a user has selected to install an integration, AgriWebb will redirect the user's browser to the partner's install URL. The partner's install endpoint begins the OAuth 2.0 Authorisation Grant flow, where the partner (OAuth 2.0 Client) creates an authorisation request to the AgriWebb auth server (OAuth 2.0 Authorisation Server). The install endpoint redirects the users' browser to the Authorisation Request route with the required parameters.

Step 2 - Authorisation Request

Please see the API Reference - Authorisation Request for technical specifications.

To begin the OAuth 2.0 Authorisation Grant flow, the partner must redirect the user to the Authorisation Request endpoint. Our implementation requires that if you receive a parameter called organization, you must pass it through to the AgriWebb auth server; this prevents the user from having to re-input their organisation.

Step 3 - Authorisation Response

Please see the Partner API Reference - Callback Endpoint for technical specifications.

Partner Endpoint Implementation Required

The browser session will be redirected to the Redirect URL (also referred to as the Callback Endpoint) when the user has accepted the partner's requested permissions (or denied the request). This endpoint is where most of the OAuth 2.0 logic will lie in the partner's implementation. If you require users to login, sign up, or accept any terms and conditions for your application here is where we recommend you implement this.

Step 4 - Token Exchange

Please see the API Reference - Token Exchange for technical specifications.

The Token Exchange endpoint can now be called using the code received from the Authorisation Response; this token exchange will provide the partner with a set of credentials, including an access token and a refresh token.

Step 5 - Set Integration Status

Please see the API Reference - Marketplace Callback for technical specifications.

Using the credentials received from the Token Exchange, the partner must call the Marketplace Callback with an integration-status set to either functional or non-functional. The user must then be redirected back to the AgriWebb Marketplace via the redirect URL provided in the response body.

At any point, you can call the Marketplace Callback with the integration-error type and provide errorUserMessage and errorDeveloperMessage. The errorUserMessage must contain an error message intended for end users. The errorDeveloperMessage must include detailed error information for AgriWebb developers and support staff.

Step 6 - Using the API

Please see the API Reference - GraphQL for technical specifications.

The GraphQL API can now be called with the credentials received from the Token Exchange.

Step 7 - Refreshing an Expired Access Token

Please see the API Reference - Token Exchange for technical specifications.

After the specified expiry time, the access token will be invalidated and the partner application will be required to request a new access token using the refresh token provided in a previous token exchange. The Token Exchange endpoint will be called with the refresh token to obtain a new set of credentials.

OAuth 2.0 Flow Diagram

Oauth 2.0 Scopes

The following scopes are available for use in the GraphQL API. Note the write: scopes do not have read permissions as that will have to be requested as a separate scope.

• 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