Accounts & Tenants

Every person and company interacting with agrirouter does so through an account. Accounts determine what you can do on the platform, whether you are a farmer connecting your machines or a developer building an integration. Getting the account and tenant model right is essential for building a correct integration.

Account Types

agrirouter has two distinct account types that serve different purposes:

End User Accounts

End user accounts are for farmers and contractors: the people who own agricultural data and want to exchange it between their software and machines. An end user account:

• Is created by a farmer or contractor through the agrirouter registration process
• Owns all endpoints connected to it
• Controls data flow through routes configured in the agrirouter UI
• Can connect any number of applications (subject to account limits)

Each agrirouter account is completely isolated, data does not flow between accounts.

Developer Accounts

Developer accounts are for app providers, the companies that build software or hardware integrations with agrirouter. A developer account sits on top of a regular end-user account: you first register as an end user, then request that the account be promoted through the developer portal. Promotion does not replace the underlying end-user account, it layers developer-specific capabilities on top so the same account can both use agrirouter like any other end user and manage registered applications.

Once promoted, a developer account adds tools for:

• Registering applications and submitting application versions for approval
• Managing OAuth credentials for your application
• Configuring integration settings and application metadata

Two practical conventions for developer accounts:

• Use a generic company email address, not a personal one, so the account stays usable when team members change.
• Plan on one developer account per app provider. All developers in your organisation share the same account.

Application and application-version management is self-service inside the developer portal. Authorization-flow credentials for your application are currently issued manually by the agrirouter team, with self-service credential creation planned for a future release.

See Setup Application for the step-by-step walkthrough from end-user signup through account promotion, application registration, and obtaining credentials.4 min

Tenant Model

In agrirouter's architecture, each account is a tenant. The tenant is the fundamental unit of data isolation:

• Every endpoint belongs to exactly one tenant
• Data exchange happens between endpoints within a tenant
• Routes are scoped to a tenant
• Resource limits (endpoint counts, message quotas) are applied per tenant

The tenant model keeps each user's data isolated from every other user's data. The platform enforces this boundary at every level, from message routing to API access.

See Tenant IDs for how tenants are identified in API calls, how the ID relates to the other IDs in an integration, and how to obtain one.4 min

Authorizations

An end user grants your application access to their tenant by completing the OAuth consent flow. The result is an authorization, the record that lets your application act under that user's tenant.

An authorization is uniquely identified by the triple (tenant_id, application_id, scope):

• tenant_id — the user's tenant.
• application_id — your application; implicit in the OAuth credentials you are calling with.
• scope — the permission granted. Today the only scope in use is endpoints:manage, which is the permission your application requests during the consent redirect. Additional scopes may be introduced in future revisions of the API; if so, authorizations with different scopes for the same tenant are treated as distinct authorizations.

A single application typically holds many authorizations at the same time, one per tenant that has connected it. Your application discovers and tracks them through two complementary mechanisms:

• Pull: GET /tenants returns every tenant for which your application currently holds an authorization, together with the related endpoints for each tenant. Use it at startup, after a crash, or whenever you need to rebuild your view from scratch. To refresh a single tenant, GET /tenants/{tenantId}/endpoints returns the endpoints currently visible there.
• Push: the SSE stream emits AUTHORIZATION_ADDED when a user grants a new authorization and AUTHORIZATION_REVOKED when one is taken away. When AUTHORIZATION_REVOKED arrives, your access to that tenant for the given scope is already gone — drop locally cached state for it.

A small privacy rule applies to the endpoints surfaced for an authorized tenant: until your application has at least one of its own endpoints in the tenant, the visible endpoints list is empty even if other endpoints exist there. Once your application creates its first endpoint, the full visible list appears and changes are reported via ENDPOINTS_LIST_CHANGED.

Applications vs. Endpoints

Two concepts that are important to distinguish:

For example, consider a company called "FarmPlan" that builds a cloud-based FMIS:

1. FarmPlan registers an application called "FarmPlan Pro" in their developer account
2. Farmer Alice connects FarmPlan Pro to her agrirouter account, which creates an endpoint in Alice's account
3. Farmer Bob also connects FarmPlan Pro to his account, which creates a separate endpoint in Bob's account
4. Alice and Bob's endpoints are completely independent, even though they represent the same application

External ID Uniqueness

External IDs for endpoints are scoped to the tenant. This means:

• The same external ID can exist for the same application in different accounts
• The same external ID cannot be used twice within the same account, even by different applications

Account Limits

Each agrirouter account has a cap on the number of endpoints it can hold. The cap depends on the account type and subscription tier. Once you hit it, no new applications can be connected until existing endpoints are removed.

See the Limitations appendix for specific account and endpoint limits.1 min

Key Relationships

How accounts, applications, and endpoints fit together:

Learn more about endpoints, their lifecycle, and how they are managed.4 min