Endpoint Management

Managing endpoints throughout their lifecycle, from creation to update to revocation

Every application instance connected to agrirouter is represented as an endpoint. This page covers the full endpoint lifecycle, from creation through ongoing management to revocation.

For the conceptual model, see the endpoints documentation.

Endpoint Lifecycle

Loading diagram...

An endpoint moves through these stages:

Stage	Description
Create	Create the endpoint with a single `PUT` request that provides the external ID, capabilities, and subscriptions.
Communicate	Send and receive messages through the platform.
Update	Reconfigure capabilities and subscriptions with another `PUT /endpoints/{externalId}` request.
Revoke	Remove the endpoint when it is no longer needed.

Creating Endpoints

Create an endpoint by sending a PUT /endpoints/{externalId} request with the endpoint's externalId. The response is the created endpoint record.

Every current-API endpoint type (cloud_software, virtual_communication_unit, and the deprecated farming_software) follows the same authorization path before an endpoint can be created: the OAuth2 client-credentials + user-consent flow described in Your First Endpoint. Each VCU is registered directly with its own PUT /endpoints/{externalId} call on the same authorization, with no parent or concentrator endpoint involved.

For physical Communication Units, see the legacy Communication Unit guide. CUs use the legacy API and its own authorization mechanism.

Discovering and syncing tenant state

A long-running integration needs an up-to-date view of two things: which tenants have authorized your application, and which endpoints are currently visible in each of those tenants. The gateway exposes both a pull-based bootstrap and a push-based update path; production integrations typically combine the two.

At startup

Call GET /tenants once your application is up. The response lists every tenant for which an authorization currently exists, together with the endpoints visible in each tenant. Use this as the seed for whatever local state your application keeps about tenants, authorizations, and endpoints.

A tenant may appear in the response with an empty endpoints array. That is the privacy rule documented on the schema: until your application has created at least one of its own endpoints in a tenant, the visible-endpoints list is empty there, even if the tenant contains other endpoints. Once you create that first own endpoint, the full visible set appears.

At runtime

Open the GET /events SSE stream and react to four event types alongside the data-flow events:

Event	What changed	Typical reaction
`AUTHORIZATION_ADDED`	A user just granted a new authorization for one of your application's scopes.	Add the tenant to your local list and start operating on it.
`AUTHORIZATION_REVOKED`	A user just revoked an authorization. Access to the tenant for the given scope is already gone.	Drop locally cached state for the tenant and stop calling APIs scoped to it.
`ENDPOINTS_LIST_CHANGED`	The set of endpoints visible to your application in a tenant changed, or a visible endpoint's capabilities or routes changed.	Replace the cached endpoint list for the tenant with the one carried by the event.
`ENDPOINT_DELETED`	One specific endpoint was deleted (by your application, by the user, or as a side effect of an authorization revocation).	Drop local state for that endpoint.

ENDPOINTS_LIST_CHANGED only fires once your application has at least one endpoint of its own in the target tenant. Until then, changes to other endpoints in the tenant are not reported.

Out-of-band refresh

If your application loses confidence in the cached list for a single tenant, GET /tenants/{tenantId}/endpoints returns the full current list for that one tenant without a global resync. Use it when a frontend component wants endpoint information without subscribing to the event stream, or when you want to verify state after a reconnect.

Updating Capabilities and Subscriptions

To update an endpoint's capabilities or subscriptions, send another PUT /endpoints/{externalId} request with the complete new configuration. This is the same endpoint used for creation: the first call creates the endpoint, and subsequent calls update it.

Each PUT request replaces all existing capabilities and subscriptions. Always include the complete set of both in every request. Omitting subscriptions leaves your endpoint without any, meaning it will not receive published messages.

A successful update returns an HTTP 200 response with the updated endpoint object. If the request fails, inspect the HTTP status code and error details. Common causes: invalid message types, or a mismatch with the software version's allowed capabilities.

About Subscriptions

Subscriptions tell agrirouter which message types to route to your endpoint's feed when other endpoints publish them. Subscriptions only affect the publish/subscribe model. Directly addressed messages are delivered regardless of subscriptions, as long as a valid route and matching capabilities exist.

Revoking Endpoints

To permanently remove an endpoint, send a delete request. The endpoint loses access to agrirouter immediately.

Since agrirouter 2.0, the revocation response is simplified: the API returns an HTTP status code with an empty body instead of a detailed response payload.

After revocation:

The endpoint can no longer send or receive messages.
Routes involving the endpoint are removed.
Unread messages in the feed are discarded.
The same externalId can be reused to create a new endpoint later.

Since agrirouter 2.0, recreating a revoked endpoint has reduced or no waiting time. Previously, a mandatory delay applied before a revoked endpoint's external ID could be reused.

Blocking Endpoint Instances

As an app provider, you can block specific endpoint instances of your application. Use cases:

Revoking access from a user who has violated your terms of service.
Disabling endpoints running outdated or unsupported versions.
Managing license compliance.

Blocked endpoints cannot communicate through agrirouter until unblocked.

Software Updates and Capability Changes

When you release a new version of your application with changed capabilities (new message types, removed message types, or changed directions):

Register a New Application Version

Register the new version in the agrirouter developer portal to get a fresh software_version_id. If the capability changes affect how your application communicates with agrirouter, the new version also goes through an implementation review before it can be used in production.

Update Each Endpoint

Update each active endpoint via PUT /endpoints/{externalId} with the new software_version_id and updated capabilities and subscriptions. Until an endpoint is updated, it keeps operating with the old capability set.

Inviting Testers

Before submitting an application version for implementation review, you can validate it against real agrirouter accounts by inviting testers:

Open your application settings in the agrirouter developer portal.
Add tester accounts by their agrirouter email address.
Invited testers can connect your pre-approval application to their agrirouter account and create endpoints under it.

Tester endpoints have full functionality but are limited to the QA environment until your application is approved for production.