Authentication

LinkOStar accepts six credentials. Each applies to a different path. If a request carries more than one, only the highest-priority one is activated. The two Supplier-OAuth-related credentials at the bottom (Supplier Bearer + HMAC) arrived in V10+ and most integrators won't touch them directly.

At a glance

1. X-API-Key (Supplier ↔ BFF)

The standard credential when a supplier BFF calls LinkOStar. Never expose it in an end-user browser — a leaked key sees data for every supplier.

curl https://api.linkostar.sandevaux.com/tenant/hubs \
  -H "X-API-Key: ${LINKOSTAR_API_KEY}" \
  -H "X-Tenant-UUID: ${LINKOSTAR_TENANT_UUID}"

2. sdx-oauth JWT (operator / end-user)

The LinkOStar operator console and the LinkOStar mobile app obtain a JWT through sdx-oauth and forward it as-is to the backend.

• The JWT identifies the user.
• X-Tenant-UUID picks which tenant scope the request runs in.
• Both headers are required for /tenant/** to succeed.

For sdx-oauth issuance and refresh (PKCE + refresh_token), see the sdx documentation.

3. Hub Bearer (hub-agent ↔ LinkOStar)

Used by hub-agent (running on the Pi) for endpoints like /v1/hubs/{uuid}/telemetry. Lifecycle:

1. On first boot, hub-agent posts the claim_code from its boot config to POST /v1/hubs/claim.
2. The response carries accessToken, refreshToken, and hubUuid.
3. Subsequent /v1/hubs/** calls send Authorization: Bearer <accessToken>.
4. Five minutes before expiry the agent refreshes via POST /v1/hubs/refresh (current access token in the header, refresh token in the body).

There is one token per hub. Refreshing invalidates the previous access token immediately; if two clients hold the old token, one of them 401s on the next call.

4. X-Tenant-UUID

Disambiguates which tenant scope a /tenant/** request runs in. The same JWT user can belong to multiple tenants, so the request needs to commit to one. The same header is required for the X-API-Key flow.

Missing the header — or carrying a tenant the user can't access — strips the tenant role and the request fails with 403 or 401.

5. Supplier Bearer (V10+)

Attached by the LinkOStar mobile app when it POSTs to a step's external_submit_url. The supplier OAuth access_token is stored AES-GCM-encrypted by LinkOStar; the app fetches it through GET /app/supplier-links/{id}/access-token right before the call and puts it in Authorization: Bearer …. Verify on the supplier side as a standard OAuth 2.1 bearer issued by your own auth server.

Any Authorization entry in configJson.external_headers is ignored — Supplier Bearer wins (D-Link-5). Full flow on Supplier OAuth.

6. HMAC-SHA256 signatures (V12+)

Both-way webhook integrity + origin proof. Both directions use the same registration_shared_secret (stored AES-GCM).

• LinkOStar → supplier: registration push (V12). Attaches X-LinkOStar-Signature: sha256=<hex> + X-LinkOStar-Event-Type + X-LinkOStar-Idempotency-Key. Verify on the supplier receiver.
• supplier → LinkOStar: POST /webhook/supplier-permission/{uuid} (V13). LinkOStar verifies the same signature before invalidating the permission cache.

A Node.js verification example lives on Supplier OAuth.

Priority / filter order

Multiple credentials in the same request: only one wins, in this order.

1. X-API-Key filter — /tenant/** only.
2. JWT filter — sdx-oauth JWT for /tenant · /app · /platform.
3. Hub-token filter — /v1/** only.

Safe handling

• Store X-API-Key in a secret manager (1Password, AWS Secrets Manager, etc.). Never commit it.
• Redact credential headers in BFF logs.
• The hub token lives in /var/lib/agent/state.json on the Pi — root-only readable.
• If a leak is suspected, contact LinkOStar ops to rotate the key.