Tenant IDs

How tenant IDs identify the end user account your application acts under, where to obtain them, and how to pass them in API requests

A tenant ID identifies the end user account that your application is acting under. Every endpoint your application creates belongs to exactly one tenant, and the tenant ID is the link between the client credentials your application holds and the specific end user account those credentials are operating on behalf of.

This page covers what a tenant is, how the tenant ID relates to other IDs in the system, where to obtain it, and how to use it.

What a tenant is

In agrirouter, every account is a tenant. A tenant is the unit of data isolation: each end user (a farmer or contractor) owns a tenant, every endpoint belongs to exactly one tenant, and routes are configured within a tenant.

A single application can act across many tenants. Each end user that connects your application to their account shows up as a separate tenant from your application's perspective. Your application has to keep a list of the tenant IDs it has been granted access to and use the right one on every request.

For the broader account model and how tenants relate to applications and endpoints, see Accounts & Tenants.

Tenant IDs and other IDs

A tenant ID is a UUID. Several other UUIDs appear in agrirouter integrations and they are easy to mix up:

ID	What it identifies	Where you encounter it
Tenant ID	The end user account your application is acting under	`x-agrirouter-tenant-id` request header, `tenant_id` field on endpoint and event payloads
OAuth client ID	Your application's identity for authentication	`client_id` parameter when requesting an access token
Application ID	The application registered in the developer portal	`application_id` field on the endpoint object
Endpoint ID	A specific endpoint inside a tenant	`id` field on the endpoint object, `x-agrirouter-endpoint-id` request header
External ID	An application-controlled identifier for an endpoint	`external_id` field on the endpoint object, path segment of `PUT /endpoints/{externalId}`

The same tenant UUID appears in two places once an endpoint exists: as the value of the x-agrirouter-tenant-id header you send, and as the tenant_id field on the endpoint object returned by PUT /endpoints/{externalId}. Both refer to the same underlying tenant.

How you obtain a tenant ID

For end user accounts, you can pick up the tenant ID through three complementary mechanisms. They all surface the same authorization, so you can mix them based on where in your application the next step is happening.

OAuth authorization callback — when a user approves your application on the consent page, the browser is redirected back to your redirect_uri with the tenant_id query parameter set to the tenant the user selected. This is the natural source when a frontend continues straight into endpoint creation. See Authorization Flow for the full redirect contract.
```
https://yourapp.com/callback?state={randomStateValue}&tenant_id={userTenantId}
```
AUTHORIZATION_ADDED SSE event — delivered on the GET /events stream when the user grants the authorization, carrying the same tenant_id along with the granted scope. This is the natural source when a backend keeps a long-lived SSE connection and reacts to authorizations there, without taking a dependency on the redirect URL.
GET /tenants — returns every tenant for which your application currently holds an authorization. This is the natural source for application startup, recovery, or any time you need to rebuild your view of authorized tenants from scratch.

There is no way to derive an end user's tenant ID from the access token; the access token is opaque.

Your application's developer-account tenant ID is a separate value. The agrirouter team issues it when your developer account is provisioned, and you use it to sign into the developer portal and manage your application record. It is not the tenant ID you pass in x-agrirouter-tenant-id on per-user API calls.

Tenant IDs are stable for the lifetime of the account and do not need to be refreshed.

How you use a tenant ID

Pass the tenant ID as the x-agrirouter-tenant-id request header on every call that operates inside that tenant.

Operation	Endpoint	Tenant header required
Create or update an endpoint	`PUT /endpoints/{externalId}`	yes
Delete an endpoint	`DELETE /endpoints/{externalId}`	yes
Send a message	`POST /messages`	yes
Confirm received messages	`POST /confirmations`	yes
Receive events	`GET /events`	no, the stream covers all endpoints across every tenant the application is authorized for

Example:

PUT /endpoints/my-external-id
x-agrirouter-tenant-id: 12345678-abcd-ef01-2345-6789abcdef01
Authorization: Bearer ...
Content-Type: application/json

Event payloads delivered through GET /events carry a tenant_id field on the event data, so a multi-tenant application can dispatch each incoming event to the right tenant context.

What not to do

Do not attempt to decode, verify, or introspect the access token to extract a tenant ID or any other information. The token format is not part of the public API and may change without notice.

Treat the access token as opaque. The tenant ID is not encoded in it, and the token's shape, claims, and signing algorithm are implementation details that may change without notice. Code that reaches into the token to pull out user or tenant information will eventually break.

For the full guidance on access token handling, see Access Tokens in Authorization & Security.

Read Accounts & Tenants for the broader account and tenant model.5 min

API Reference

The tenant ID header is required on every operation below. Open them in the API playground to see the header in context:

Create or update endpoint1 min Delete endpoint1 min Send one or several messages1 min Confirm received messages1 min