Connecting a Data Source via OAuth

Some data sources — John Deere, CASE, Wacker Neuson, and others — don't accept a static API key. Instead, the equipment owner must log in on the manufacturer's own portal and explicitly grant Hiboo access. This is the standard OAuth2 authorization code flow, and this guide walks through how to drive it from your own application.

Why OAuth

The whole point of the OAuth2 flow is that your application — and Hiboo — never see the end user's personal data source credentials (their email and password on the manufacturer's portal).

Instead:

1. The user's browser is sent directly to the data source's own login/consent page.

2. On success, the data source hands Hiboo a short-lived authorization code.

3. Hiboo exchanges that code for an access token and a refresh token, which it then uses to pull equipment data on an ongoing basis.

Some data sources also require supplementary app credentials to identify the calling application — typically a clientId / clientSecret pair issued by the manufacturer. Where required, you pass these along as integrationCredentials when you start the flow — see Supported data sources below.

The three actors

Actor	Role
Your application	A partner frontend. Starts the flow and receives the final redirect.
Hiboo API	Creates and tracks the OAuth session, exchanges the code for tokens, and creates or updates the Integration.
Data source's OAuth portal	Where the end user authenticates and consents (e.g. signin.johndeere.com).

Base URL: the OAuth endpoints below are served from https://ingest.hiboo.io.

Flow overview

1. Your backend calls POST https://ingest.hiboo.io/catalog/integrations/oauth with the data source and the credentials you already have. Hiboo creates a pending OAuth session and returns an oauthUrl and a sessionId.

2. You open oauthUrl in the user's browser. The user logs in directly with the data source.

3. The data source redirects the browser to Hiboo's fixed callback URL (https://ingest.hiboo.io/oauth/callback) with an authorization code and state (the sessionId).

4. Hiboo exchanges the code for tokens, creates the Integration, and redirects the browser to the redirectUri you provided in step 1.

5. Optionally, you can poll GET https://ingest.hiboo.io/catalog/integrations/oauth/{sessionId} to fetch the outcome server-side instead of relying solely on the redirect.

Don't confuse the two URLs:

• Callback URL — constant, owned by Hiboo (https://ingest.hiboo.io/oauth/callback). This is where the data source sends the user back to.

• Redirect URL — yours, passed as redirectUri. This is where Hiboo sends the user back to once the exchange is done.

Step 1: Start the OAuth session

POST https://ingest.hiboo.io/catalog/integrations/oauth
x-access-token: <your organization admin token>
Content-Type: application/json

{
  "dataSourceCode": "wacker_neuson_aemp_2",
  "integrationName": "Wacker Neuson - Main fleet",
  "integrationCredentials": {
    "clientId": "your-wacker-neuson-client-id",
    "clientSecret": "your-wacker-neuson-client-secret"
  },
  "redirectUri": "https://app.hiboo.io/integrations/oauth/callback"
}

Body parameters:

Field	Description
dataSourceCode	One of the supported OAuth data sources.
integrationName	A name for the resulting Integration.
integrationCredentials	Supplementary credentials the data source requires ({} if none — see Supported data sources).
redirectUri	Where Hiboo sends the user's browser once the flow completes, success or failure.

Requires an authenticated organization admin (x-access-token header, admin role).

Response — 200 OK:

{
  "oauthUrl": "https://signin.johndeere.com/oauth2/.../v1/authorize?client_id=...&state=...",
  "sessionId": "b3f1c2a4-....."
}

Status	Cause
401	Missing or invalid token.
403	Authenticated user is not an organization admin.
409	An Integration already exists for this organization, data source, and credentials.
422	Unsupported dataSourceCode, or invalid body.

Step 2: Send the user to the data source

Redirect the browser (or open a webview) to the oauthUrl returned in step 1. The user authenticates and consents entirely on the data source's own domain — your application is not involved in that exchange.

Step 3: The data source calls Hiboo back

The data source redirects the browser to Hiboo's callback endpoint with the authorization code and the state you never touch directly — it's the sessionId from step 1, round-tripped for you:

GET https://ingest.hiboo.io/oauth/callback?code=<authorization-code>&state=<sessionId>

Hiboo looks up the pending session by sessionId, exchanges the code for an access token and a refresh token with the data source, and creates the Integration (storing the tokens as its credential).

Step 4: Hiboo redirects back to your application

Once the exchange completes (or fails), Hiboo redirects the browser to the redirectUri you supplied in step 1, with query parameters appended:

On success:

https://app.hiboo.io/integrations/oauth/callback?status=completed&integrationId=42&sessionId=b3f1c2a4-...

On failure:

https://app.hiboo.io/integrations/oauth/callback?status=error&sessionId=b3f1c2a4-...

The error redirect does not include the failure reason — read it via step 5 if you need to display it to the user.

Step 5 (optional): Poll for the result

If you'd rather confirm the outcome from your backend than parse redirect query parameters — useful for mobile deep links, or as a safety net if the redirect gets interrupted — poll:

GET https://ingest.hiboo.io/catalog/integrations/oauth/{sessionId}
x-access-token: <your organization admin token>

Response — 200 OK:

{ "status": "completed", "integrationId": 42 }

or

{ "status": "error", "reason": "Failed to authenticate with John Deere: invalid_grant" }

Status	Cause
404	No result for this sessionId — not found, expired, or not yet completed. Results are kept for 5 minutes after completion.
403	The session belongs to another organization.

Re-authenticating an existing Integration

Access and refresh tokens can be revoked or expire. To reconnect an existing Integration without recreating it, start the same flow against the Integration instead of the data source:

POST https://ingest.hiboo.io/catalog/integrations/{integrationId}/oauth
x-access-token: <your organization admin token>
Content-Type: application/json

{
  "redirectUri": "https://app.hiboo.io/integrations/oauth/callback"
}

This reuses the Integration's stored credentials and data source, so you don't repeat dataSourceCode or integrationCredentials. Steps 2–5 are identical — on success, the existing integrationId is reactivated with fresh tokens rather than a new Integration being created.

Status	Cause
404	No Integration with this integrationId.
403	The Integration belongs to another organization.
422	This data source no longer supports OAuth, or invalid body.

Supported data sources

dataSourceCode	Data source	Supplementary integrationCredentials
johndeere_aemp_2_0	John Deere (AEMP 2.0)	None — pass {}
johndeere_operations	John Deere Operations Center	None — pass {}
case_aemp_2	CASE (AEMP 2.0)	None — pass {}
wacker_neuson_aemp_2	Wacker Neuson (AEMP 2.0)	clientId, clientSecret (issued to you by Wacker Neuson)

Pending session lifetime

An OAuth session created in step 1 is only held for 15 minutes. If the user doesn't complete the data source login within that window, the sessionId expires and the callback in step 3 will fail — start over from step 1.