Your First Endpoint

Obtain an access token

Your application authenticates itself using the OAuth2 Client Credentials flow. This is independent of any user interaction: you can request a token at any time, for example at application startup.

curl -X POST https://api-oauth.agrirouter.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id={yourClientId}&client_secret={yourClientSecret}"

The response contains a signed JWT (JSON Web Token):

{
  "access_token": "eyJhbGciOiJFUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Only the value of the access_token field is the Bearer token. Do not include the full JSON object or the surrounding quotes when you set the Authorization header:

Authorization: Bearer eyJhbGciOiJFUzI1NiIs...

Store this token and include it on all subsequent API requests. Request a new token before it expires. You should only use the information in expires_in to schedule the next refresh and you should not try to parse the token itself. We do not guarantee the structure or content of the token, you need to treat it as opaque (pass it as-is, without any transformation or introspection).

Set up the user consent redirect

When a user wants to connect your application to their agrirouter account, redirect their browser to agrirouter's consent URL:

https://app.agrirouter.com/api/authorize?client_id={yourClientId}&redirect_uri={yourRedirectUri}&scope=endpoints:manage&state={randomStateValue}

The user sees a consent page where they can Connect or Reject your application. If client_id or redirect_uri is missing, malformed, or does not match the registered values, the consent page renders an error instead of the consent prompt — the user has no way to grant authorization in that case, so make sure both parameters are present and correct before redirecting.

Handle the redirect back

After the user makes a choice, the browser is redirected back to your redirect_uri:

On approval:

https://yourapp.com/callback?state={randomStateValue}&tenant_id={userTenantId}

On rejection:

https://yourapp.com/callback?error=access_denied&state={randomStateValue}

Your application should:

1. Verify the state parameter matches the value you originally sent (to prevent CSRF attacks)
2. Check for the error parameter. If present, the user denied the request.
3. Store the tenant_id parameter (approval only). This is the tenant ID of the end user account the user selected on the consent page. Use it as the x-agrirouter-tenant-id header on every subsequent API call you make on this user's behalf.

Get your tenant ID

The tenant ID identifies the end user account your endpoint will belong to. Use it as the x-agrirouter-tenant-id request header on every call to PUT /endpoints/{externalId} and the other endpoint-management operations for this user.

You can pick up the tenant ID from either of two sources, depending on which side of your application is driving the next step:

• From the redirect query parameter — the tenant_id value on the authorization callback shown above. This is the natural choice when the frontend continues straight into endpoint creation, for example when the same browser session calls back to your backend with the parsed query.
• From the AUTHORIZATION_ADDED SSE event — delivered on the GET /events stream when the user grants the authorization, carrying the same tenant_id together with the granted scope. This is the natural choice when a backend keeps a long-lived SSE connection and reacts to authorizations there, without taking a dependency on the redirect URL.

Both sources surface the same authorization. Pick the one that fits your architecture, or use both — for example, the frontend stores the tenant ID for the immediate next call and the backend independently picks it up from the event to update its own state.

To list every tenant your application is currently authorized for (for example, on application startup or after a crash), call GET /tenants.

Your application's own developer-account tenant ID (used to sign into the developer portal) is a separate value issued with your OAuth credentials. That is not the tenant ID you pass on per-user API calls.

Choose an external ID

Every endpoint needs an external ID, a unique identifier your application uses to reference this endpoint instance. Use the URN format:

urn:<your-domain>:<application>:<instance-identifier>

For example:

urn:mycompany.com:farmapp:user-12345

Create the endpoint

Send a PUT request to the endpoints API with your access token and chosen external ID. The example below focuses on the fields you will edit most often; open the API reference for the full schema and to try it against your own data.

The request body includes:

• name (optional): a human-readable label shown in the agrirouter web interface, 1-200 characters of letters, digits, spaces, and -, _, ., ,, :. If you omit it, agrirouter generates one for you. Names do not have to be unique, and the user can rename the endpoint in the web interface; once they do, later PUT calls will not overwrite their choice.
• application_id and software_version_id: the UUIDs of your registered application and its version (received during application registration in Setup Application)
• endpoint_type: the type of endpoint, either cloud_software or virtual_communication_unit (see Endpoint Types)
• capabilities: the message types your endpoint can handle, each with a direction (SEND, RECEIVE, or SEND_RECEIVE)
• subscriptions: the message types your endpoint wants to receive through the publish and subscribe model

For the full conceptual model, see Capabilities and Subscriptions on the Messaging concepts page.

A successful response returns the endpoint details, including the agrirouter-generated endpoint ID, a UUID you will need when sending messages.

Verify in the agrirouter UI

Log in to the agrirouter UI and navigate to your account's endpoint list. Your newly created endpoint should appear with:

• The name of your application
• The capabilities you configured
• An active status