Integrations

Fleet integrates with other The One Stack products via shared Hub authentication and The One Bus event mesh. External systems can also integrate via the Fleet Integration API.

Hub — Authentication and Identity

What it does: Hub provides SSO authentication for Fleet. All user sessions are validated against the Hub IAM service.

Data flow: Hub → Fleet (auth tokens, org context, user roles)

How it works:

• Users log in to Fleet through the Hub SSO flow
• Fleet validates the Hub session cookie (fleet_session) on every API request
• The user's Hub organization maps to a Fleet tenant
• Hub org roles (owner, admin, member, viewer) map to Fleet roles

What breaks if misconfigured: Users cannot log in to Fleet. All authenticated API requests return 401.

PSA — Field Dispatch Integration

What it does: PSA dispatchers can query vehicle locations and driver assignments when scheduling field technician trips.

Data flow: PSA → Fleet (reads vehicle list and current GPS location)

Endpoints used:

Endpoint	What It Returns
GET /api/integration/vehicles?tenant_id=...	List of all active vehicles with name, status, and assigned driver
GET /api/integration/vehicle-location?vehicle_id=...&tenant_id=...	Latest GPS coordinates for a specific vehicle

Authentication: Service-to-service calls use an X-Integration-Key header. The integration key is set in Fleet's Admin panel.

What breaks if misconfigured:

• PSA cannot show vehicle locations on the dispatch map
• PSA "nearest vehicle" suggestions won't work
• Dispatchers must manually look up vehicle assignments

ℹ️The integration key for PSA→Fleet must be configured in both systems: set the key in Fleet Admin, then enter the same key in PSA's Fleet integration settings.

The One Bus — Event Emission

Fleet emits events to The One Bus for major state changes. Other products can subscribe to these events to trigger workflows.

Events Emitted by Fleet

Event	When It's Emitted	Payload
vehicle.created	New vehicle added	vehicle_id, vehicle_number, name
vehicle.updated	Vehicle record updated	vehicle_id, vehicle_number, name
vehicle.deleted	Vehicle soft-deleted	vehicle_id, vehicle_number, name
maintenance.created	New maintenance record created	maintenance_id, vehicle_id, maintenance_type
maintenance.updated	Maintenance record updated (e.g., completed)	maintenance_id, vehicle_id, status
maintenance.deleted	Maintenance record deleted	maintenance_id, vehicle_id
gps.position_recorded	GPS position(s) saved	count, vehicle_ids
gps.geofence_breach	Vehicle exited a geofence	vehicle_id, latitude, longitude, breaches
inventory.created	New inventory item added	inventory_id, name, sku
inventory.updated	Inventory item updated	inventory_id, name, quantity
order.created	Purchase order created	order_id, order_number, total, item_count
order.updated	Purchase order status changed	order_id, order_number, status, total

How to subscribe: Register a Bus consumer in your product for the fleet source. See The One Bus documentation for consumer setup.

What breaks if Bus is unavailable: All Fleet operations continue normally — Bus emits are best-effort and wrapped in try/catch. No Fleet data is lost if Bus is down, but downstream consumers won't receive events.

Inbound Webhooks

Fleet can receive events from external products via its webhook endpoint:

POST /api/integration/webhook
{
  "event_type": "ticket.dispatched",
  "source": "psa",
  "tenant_id": "your-tenant-id",
  ...payload
}

Authentication: Requires an X-Integration-Key header.

What it does: Logs the received event to the Fleet audit trail. Use this to track when PSA dispatches a technician so you can correlate with GPS data.

Books — Billing

What it does: Books handles Fleet's usage-based billing. The Fleet entitlement is checked at login to determine feature access.

Data flow: Books → Fleet (entitlement checks)

What breaks if misconfigured: Users may see incorrect feature access or be denied access to Fleet entirely.

Integration Health Check

To verify that Fleet's integration endpoints are available:

GET /api/integration/health

Returns:

{
  "status": "ok",
  "product": "fleet",
  "version": "1.0.0"
}

Use this endpoint for uptime monitoring or integration smoke tests.

Configuring Integration Keys

1. Navigate to Admin in the Fleet sidebar
2. Open API Keys or Integrations
3. Generate or copy the integration key
4. Provide this key to the integrating product (PSA, external GPS platform, etc.)

Integration keys authenticate service-to-service calls. They bypass user-level auth and operate at the tenant level, so treat them as secrets.