LinkOStar Documentation
LinkOStar is a shared platform for IoT device connectivity, onboarding, and observability. Multiple suppliers publish their own devices and bundles; end-users install hubs that bind to them. This site is the single entry point for any supplier, BFF, or operations partner integrating with LinkOStar.
What you'll find here
- Live spec — an OpenAPI definition that updates as soon as code ships (/api-docs) plus a Swagger UI (/swagger-ui/index.html).
- Integration patterns — the typical shape of a supplier BFF calling LinkOStar, with recommended practices.
- Cross-cutting conventions — authentication, response envelopes, pagination.
- Data model and architecture — how entities relate and which component owns which responsibility.
- Changelog — what changed, when, and how much notice you get before breaking changes.
What you won't find here
- Supplier-specific business data — API keys, supplier_uuid, BFF hostnames belong in the supplier organisation's own secret manager.
- Pricing & contracts — covered separately under sdx-billing.
- Internal decision history — lives in the
LinkOStarrepo's SSOT markdown and isn't intended for external publication.
Page index
Integration Guide
How to wire LinkOStar from a supplier console or BFF. Common endpoints, auth flow, SDK generation.
API Reference
Swagger UI · OpenAPI 3.0 spec. Auto-updated whenever the backend ships.
Authentication
X-API-Key · sdx-oauth JWT · X-Tenant-UUID · hub bearer · Supplier Bearer · HMAC — which credential each path needs.
Supplier OAuth
User ↔ supplier account linking, permission sync, registration push. Supplier registration runbook.
Permission Model
LinkOStar vs. supplier SSOT split + OWNER/OPERATOR/VIEWER hierarchy + cache.
Outbox Pattern
Activation outbound + supplier registration push share the same shape. Supplier receiver guide.
Response Envelopes
{ data, pagination } envelope · error shape · status code conventions.
Data Model
Core entities (Tenant · SupplierBundle · HubInstance · SupplierLink · …) and their relationships.
Architecture
How hub-agent · backend · web · mobile · supplier BFF · supplier OAuth mesh together.
Changelog
Versions · breaking-change notice SLA · migration notes.
Support
SLA · contact channels · incident response.
First-time integration
Start with Architecture for the system picture, then read Authentication and the Integration Guide. Most integration scenarios are wired up within 30 minutes of finishing those three pages.
If your supplier connects its own identity / permission model into LinkOStar, follow up with Supplier OAuth → Permission Model → Outbox Pattern.