Remote Application Connection
Let your users easily connect your application to another one
Remote Application Connection (RAC) lets a user start from your solution, pick another agrirouter application, and end up with working routes between the two — without being asked to find their way through agrirouter on their own. Your application redirects the browser once, agrirouter drives login, onboarding of both sides and route creation, and the user is handed back to you with a result.
The application that starts the flow is the initiating application. The application being connected to is the target application. Both are identified by their catalog application_id.
Prerequisites
Set up Single Sign-On
RAC is entered through your SSO integration: the start URL requires the idp_alias slug assigned to your solution, and the user is authenticated against your Identity Provider before anything else happens. Without SSO in place the flow cannot be started.
Register your application and its capabilities
Compatibility with other applications is computed from the message types declared on your application's software version. An application that declares no capabilities matches nothing and cannot be connected.
Cloud Software4 minConfigure the redirect URLs
The URL agrirouter returns to at the end of the flow must be registered in advance. In the agrirouter UI, open Developer → Applications, select your application, and add the URL under Technical details → Remote Application Connection → Redirect URLs.
Matching is an exact string comparison — no wildcards, no prefix matching, no normalisation of trailing slashes. A redirect_uri that is not on the list causes the connection request to be rejected.
The list is re-checked when the connection is completed, not only when it is started. Removing a URL while connections are still in progress causes those connections to fail at the final hand-back.
Discovering compatible applications
Your application can present the agrirouter applications it is compatible with — in a picker, a marketplace page, or anywhere that fits your UI — and offer your users a Connect action that starts the RAC flow for the one they choose. The list can be retrieved from the G4 API:
GET /compatible-applications?initiating_application_id=<your-application-id>The request is authenticated with your own client-credentials access token, and initiating_application_id must match the application that token belongs to — a mismatch is answered with 403.
Compatibility is derived from declared capabilities alone, so the list is available before any endpoint exists for either side. An application is returned when messages could flow in at least one direction and it is visible to you — that is, published in the agrirouter catalog, or owned by the same tenant as your own application. The second half of that rule lets a vendor wire up their own applications before publishing them.
{
"compatible_applications": [
{
"application_id": "1f9a8c62-3c1e-4a5b-9c4b-0f2f1a7d8e11",
"name": "IO-Tool",
"brand": "DKE-Data",
"description": "Test and diagnosis tool for agrirouter",
"logo_url": "https://images.agrirouter.com/logos/io-tool.png",
"type": "FARMING_SOFTWARE",
"compatible_capabilities": {
"can_send": ["iso:11783:-10:taskdata:zip"],
"can_receive": ["iso:11783:-10:taskdata:zip", "iso:11783:-10:time_log:protobuf"]
}
},
{
"application_id": "8d3b7e51-2a4c-4f6d-8e1b-7c9d0a2b3f44",
"name": "CCI A3",
"brand": "CCI",
"type": "COMMUNICATION_UNIT",
"compatible_capabilities": {
"can_send": ["iso:11783:-10:time_log:protobuf"],
"can_receive": ["iso:11783:-10:taskdata:zip"]
}
}
]
}compatible_capabilities is expressed from the target's perspective: can_send lists what the target could send to your application, can_receive what it could receive from it.
type is the catalog type of the target, and it is the field that decides how the connection is made:
type | How the target is connected |
|---|---|
COMMUNICATION_UNIT | A registration code shown by agrirouter and typed into the machine's terminal by the user. |
FARMING_SOFTWARE, TELEMETRY_PLATFORM, G4_APPLICATION | The target's own Deep URL, where the user authorizes it. |
Machines are legitimate, connectable targets, but connecting requires the user enter the registration code on a terminal. Consider using type to label or group them in your picker.
brand, description and logo_url are optional and are omitted when the catalog entry does not provide them. Build the picker so a missing logo does not break the layout.
Starting the flow
The flow is started by redirecting the user's browser to:
https://app.agrirouter.com/api/remote-app-connection/startThe following query parameters can / must be set:
| Parameter | Required | Description |
|---|---|---|
initiating_application_id | Yes | Your application's catalog ID, as a UUID. |
target_application_id | Yes | The catalog ID of the application to connect to, as a UUID, taken from the discovery response. |
redirect_uri | Yes | Where agrirouter returns the user at the end of the flow. Must match one of the registered redirect URLs exactly. |
state | Yes | An opaque value echoed back unchanged on the return redirect. 1–512 characters from A-Z a-z 0-9 _ . ~ -. |
idp_alias | Yes | The SSO slug assigned to your solution. Determines which Identity Provider the user is authenticated against. |
locale | No | Interface language for the agrirouter screens. One of de, en, es, fr, it, nl, pl, pt-BR, ru. An unrecognised value is ignored and a language that's determined by the user's browser is used instead. |
company_name | No | Company name for a user who has no agrirouter account yet. 1–256 characters. |
country_code | No | Country for a user who has no agrirouter account yet, as an ISO 3166-1 alpha-2 code (for example DE). |
A complete start URL looks like this:
https://app.agrirouter.com/api/remote-app-connection/start
?initiating_application_id=8f2c1b40-6f7a-4c1e-9a3d-5e6f7a8b9c0d
&target_application_id=1f9a8c62-3c1e-4a5b-9c4b-0f2f1a7d8e11
&redirect_uri=https%3A%2F%2Fpartner.example.com%2Frac-callback
&state=7c9f1d2e4b6a8c0e
&idp_alias=iotool
&locale=deBoth parameters only apply to users who do not have an agrirouter account yet, and are ignored for everyone else. When both are supplied, the account is created from them silently and the user is never asked. When only one is supplied, the account creation dialog is shown with that field pre-filled. Send whichever details you have — a single value still saves the user a step.
A missing required parameter, or any parameter present with a malformed value, is answered with 400 and a plain-text message naming it, before any redirect happens. This includes the optional company_name and country_code: omitting them is fine, but sending an empty, over-long or unrecognised value is not. locale is the exception — an unrecognised value is ignored rather than rejected. Validate the values you build the URL from rather than relying on the user seeing that response.
Native and mobile applications
The flow is a browser flow from beginning to end, so a native application starts it by handing the start URL to the device's browser instead of displaying it itself. Most mobile platforms provide a browser component for exactly this purpose, and using it keeps the user's existing agrirouter session available. The flow cannot be shown inside your own app: the sign-in screen refuses to be embedded in another page, and a private web view would ask the user to sign in again on every launch.
Set redirect_uri to your app's own URL scheme, for example myapp://rac-callback, rather than to a web address. Both are accepted, but the hand-back is an ordinary browser redirect, and a web address does not reliably reach a native app.
Connecting the target application takes the user out of agrirouter, and the connection is only finished once they come back. A browser session that is discarded in between loses the link back to your application: the connection is left pending, is finished later inside agrirouter, and the user is not redirected to your redirect_uri.
What the user experiences
Authentication
The user is signed in through your Identity Provider, using the SSO integration identified by idp_alias. Users who already have an active agrirouter session skip this.
Session creation
agrirouter records a resumable connection session for the tuple of user, tenant, initiating application and target application. Re-firing the same start URL resumes that session rather than creating a duplicate.
Initiator check
agrirouter checks whether an endpoint exists for your application in the user's account. If none does, the flow stops immediately and the user is sent back to your redirect_uri with result=initiating_app_onboarding_required.
Target hop
What happens here depends on the target's type.
Software Application targets
The target application is opened at its registered Deep URL so the user can authorize it there, and agrirouter waits for the target's endpoint(s) to appear. How the target is opened depends on the kind of integration it uses:
- Integrations handled inside agrirouter: these targets (e.g. John Deere Operation Center and FarmENGAGE) are connected by agrirouter itself rather than by sending the user to an external site. These take over the same tab, and the user is brought back automatically once the target is connected. The user is then shown the pending connection and should select "Resume".
- All other targets: the Deep URL is opened in a new tab. agrirouter cannot observe what happens there, so the user has to return to the agrirouter tab themselves after connecting. A screen naming the target is shown in the original tab for exactly that reason, and it stays there until the target's endpoint is detected.
Opening that new tab is attempted automatically, but browsers block windows opened without a user gesture. When the automatic attempt is blocked, the waiting screen's Continue button opens the target from a real click instead, so the user is never stranded.
The wait is bounded at three minutes. If the target's endpoint has not appeared by then, the connection is kept as a pending connection in agrirouter and the user is left on the agrirouter home page, where it can be resumed later, rather than being redirected back to your application.
Communication Unit targets
agrirouter creates a pending endpoint for the communication unit and shows the registration code that has to be entered on the machine's terminal. The code is valid for 24 hours and can be refreshed in place when it expires.
A Continue later action leaves the connection pending and sends the user to the agrirouter home page, where the machine is shown on the canvas with a Pending badge and the connection can be resumed. Resuming re-uses the code already issued for that session rather than minting a second one.
The step completes when the code is redeemed on a machine. A registration code is valid for any Communication Unit application, so redemption is what is waited for, not a match against the target's application_id: a user who walks to a different terminal than the one they picked still ends up connected.
Discarding a connection whose code has not been redeemed does not delete the pending endpoint. It stays on the user's canvas, where it can be cancelled separately.
Route creation
Once both sides have endpoints, routes between them are created automatically from the overlapping capabilities, and the user is shown a scoped canvas where those routes can be adjusted. Confirming with Done finalises the session and returns the user to your redirect_uri.
Interpreting the result
Every hand-back is a redirect to your redirect_uri with the state you supplied plus a result parameter:
result | Meaning | What to do |
|---|---|---|
connection_successful | The routes were created and the user confirmed the connection. | Treat the connection as established and continue in your UI. |
initiating_app_onboarding_required | The user has no endpoint for your application, so there is nothing to route to. | Onboard the user (authorization flow plus PUT /endpoints/{externalId}), then start the flow again. |
user_rejected | The user cancelled the connection. | Return the user to where they started. The connection was not completed. |
Always compare the returned state against the value you generated before acting on the result, and treat any unrecognised result value as "not connected".
A result redirect is only sent when the user finishes in direct continuity with a launch from your application — in the same browser, within a short window of that launch. Someone who steps away and picks the pending connection up much later, or in a different browser, completes it inside agrirouter, and your redirect_uri is not called. Do not treat the absence of a callback as failure: a connection may still exist.
Handling initiating_app_onboarding_required
This is the one result that is expected during normal operation. It says only that no endpoint for your application exists in the user's agrirouter account, which has two possible causes: the user has never authorized your application with agrirouter, or the authorization exists but no endpoint has been created against it yet.
Handle both by walking the same two steps and then re-entering the flow:
Obtain authorization
Redirect the user through the agrirouter authorization flow to obtain a tenant_id for their account. This requires a real user interaction and cannot be done in the background.
Create the endpoint
Call PUT /endpoints/{externalId} with that tenant_id, your application_id and software_version_id, and the capabilities you declared.
Retry the connection
Redirect to the start URL again with the same target_application_id and a freshly generated state.
Bound the number of retries. If a stale tenant_id is reused (for example one cached from a different login), the endpoint is created against an account that does not match the current session, agrirouter keeps reporting initiating_app_onboarding_required, and an unbounded retry loop bounces the user between the two applications indefinitely.
Session lifetime
An unfinished connection stays resumable: it is listed as a pending connection in the agrirouter UI, where the user can either finish or discard it. Sessions are removed once they are completed or discarded, and expire after 7 days.
Because a session is keyed on the user, tenant and the two applications, restarting the flow for the same pair is safe: it refreshes the existing session instead of accumulating duplicates.