Integration Guide

The most common shape of a supplier integration: a Backend-for-Frontend (BFF) that translates the supplier's session into LinkOStar credentials and aggregates raw resource APIs into screen-shaped responses. LinkOStar deliberately exposes only raw resources — cross-resource aggregation is your job.

1. Pattern (BFF + Proxy)

The supplier console and any end-user clients (mobile, web) should not call LinkOStar directly. A supplier-owned BFF sits between them and does two things:

1. Credential translation: receives the end-user's supplier-side session and forwards LinkOStar requests with the supplier's X-API-Key.
2. Aggregation: composes multiple LinkOStar endpoints into screen-friendly payloads.

Supplier UI ──(supplier session)──▶ Supplier BFF ──(X-API-Key + X-Tenant-UUID)──▶ LinkOStar
                                       │
                                       └── aggregation / cache / authorisation

2. Prerequisites

• X-API-Key: a supplier-scoped secret. See Authentication.
• X-Tenant-UUID: scopes the request. One per supplier.
• Base URL: https://api.linkostar.sandevaux.com in production.

3. Endpoint categories you'll call

The full list is in API Reference. By category:

4. Worked example — a 4-tile dashboard

Suppose the supplier console renders four tiles: hub count / device count / active alerts / system status. LinkOStar deliberately does not expose a /dashboard/stats — cross-resource aggregation is BFF territory. In your BFF:

// Supplier BFF (Java example)
long hubCount    = totalElementsFromList("tenant/hubs");
long deviceCount = totalElementsFromList("tenant/devices");
return new DashboardStatsResponse(hubCount, deviceCount, activeAlerts, systemStatus);

private long totalElementsFromList(String path) {
    Map<String,Object> resp = linkostar.get(path + "?page=1&size=1");
    return ((Number) ((Map<?,?>) resp.get("pagination")).get("totalElements")).longValue();
}

Asking for page=1&size=1 and reading pagination.totalElements is the lightest possible count query. See Envelopes.

5. Generated SDKs

Point an OpenAPI generator at the live spec (/api-docs). Generating the client in CI and diffing against the last build is the cheapest way to surface breaking changes before they hit production.

# Java
openapi-generator-cli generate \
    -i https://api.linkostar.sandevaux.com/api-docs \
    -g java -o ./generated-linkostar-client \
    --additional-properties=library=resttemplate

# TypeScript
openapi-generator-cli generate \
    -i https://api.linkostar.sandevaux.com/api-docs \
    -g typescript-fetch -o ./generated-linkostar-client

6. Patterns & anti-patterns

• ✅ Unwrap the envelope in the BFF; the supplier UI should only see flat objects.
• ✅ Treat a LinkOStar 5xx as recoverable in the BFF so one tile's outage doesn't 500 the whole page.
• ✅ Auto-generate the LinkOStar client and run an OpenAPI spec diff on every CI build.
• ❌ Never call LinkOStar from an end-user browser — the X-API-Key would leak.
• ❌ Don't ask LinkOStar for supplier-specific aggregations — build them in your BFF.
• ❌ Don't hard-code the envelope shape — list endpoints always return {data, pagination}, singles return {data}.

7. Sandbox / local development

Production: https://api.linkostar.sandevaux.com.
Local: http://localhost:8080 (run ./mvnw spring-boot:run in the backend repo).
No dedicated staging environment yet — contact LinkOStar ops if you need one.

8. Supplier integration model (V9~V13)

LinkOStar is a general-purpose hub-device connectivity platform; suppliers run their own services on top. To keep the "data stays on the supplier" model, a supplier only has to implement the four contracts below.

8.1. Claim-code metadata (V9)

When calling POST /tenant/hubs/claim-codes, attach your own identifiers (owner / space / spot / order ref) as a JSON string in the metadatafield. LinkOStar doesn't parse it; at claim time it is copied verbatim to hub_instance.metadata and returned by GET /tenant/hubs/{uuid}. You get your own mapping back without any side-channel storage.

8.2. Two-mode provisioning submit (V9)

When you create a step via POST /tenant/provisioning-steps, set the following keys in configJson to have the mobile app POST directly to your endpoint instead of going through LinkOStar:

• external_submit_url: the supplier endpoint the app POSTs to
• external_headers: extra headers the app should attach (Authorization is reserved — Bearer always wins)
• track_state_in_linkostar: false: skip the PENDING row during bundle expansion

Omit them and the existing LinkOStar submit endpoint stays as the default.

8.3. Supplier OAuth + permission sync (V10~V13)

A user links their LinkOStar account to a supplier account → if the supplier acts as the permission SSOT, /app/hubs · /app/devicesresponses are filtered by the supplier's view of permissions. See Supplier OAuthfor the full flow.

8.4. Hub / device registration push (V12)

Register hub_registration_url / device_registration_url and LinkOStar will POST hub / device creations to those URLs with an HMAC signature and an idempotency header. The supplier only has to verify the signature in its receiver.