API Reference

Claim hub instance

Register a hub to a usage unit using a claim code. **Process:** 1. Validates the claim code (expiration, revocation, usage limits) 2. Creates new hub_instance or updates existing one by device_instance_id 3. Checks if hub is blocked (rejects if blocked) 4. Generates access_token and refresh_token 5. Saves to hub_auth_token table 6. Records audit log **Security:** - No authentication required (public endpoint) - Claim code acts as authorization - Blocked hubs cannot claim **Rate Limiting:** None (one-time operation)

Sign hub CSR

Hub 가 device-local keypair 로 만든 PKCS#10 CSR 를 제출. LinkOStar 가 sign 후 client cert 를 돌려줌. cert 의 CN/SAN 은 backend 가 신뢰하는 hub_uuid 로 강제 — CSR 의 subject 는 무시.

Get current DesiredState for this hub (poll)

Resolve a scanned BLE asset to a device instance and activate it

Record job event

Record job event and update job status

Record log

Record log entry from hub

Record telemetry

Record telemetry data from hub

Snapshot inventory upsert + missing-row power-off

Idempotent: replays produce the same end-state. supplier_uuid / role 같은 운영자 지정 값은 보존 (덮어쓰지 않음).

Root CA PEM

Agent 가 trust store 에 박을 LinkOStar root CA 인증서.

Refresh hub access token

Refresh hub access token using refresh token. **Process:** 1. Validates hub authentication (must be authenticated) 2. Checks if hub is blocked (rejects if blocked) 3. Verifies refresh token matches stored token 4. Checks if token is revoked 5. Generates new access_token (refresh token remains the same) 6. Updates hub_auth_token table 7. Records audit log **Security:** - Requires hub authentication (Bearer token) - Blocked hubs cannot refresh - Revoked tokens cannot be refreshed **Token Expiration:** - Access token: 24 hours (configurable) - Refresh token: 30 days (configurable)

현재 hub의 tenant 소속 device + identifier + protocol + HUB-layer route 묶음

List hubs

List all hubs for current unit with READ permission check

Get hub detail

Get hub detail with READ permission check

Update hub label

Tenant 측에서 hub_identifier 같은 운영 라벨을 수정. PATCH 의미 — null 필드는 그대로 둠.

이 hub가 가진 BlueZ adapter 전부

adapter role / supplier 할당 변경

List apps scheduled / installed on this hub

Get hub jobs

Get hub jobs with READ permission check

Get hub logs

Get hub logs with time range filter

List setup delegations

List all setup delegations for a hub

Create setup delegation

Delegate hub setup rights to another user

Revoke setup delegation

Revoke a setup delegation

Get hub telemetry

Get hub telemetry with time range filter

List my claim codes

Newest first; status is derived (PENDING/USED/EXPIRED/REVOKED)

Generate claim code

Generate a new hub claim code for this tenant

Hard-delete (unused) or soft-revoke (used) a claim code

List device instances (optionally filter by activationStatus)

Register new device instance

Get device instance detail

Delete device instance

Update device instance

Force-activate device instance (manual override)

Retire device instance (terminal state)

Query sensor timeseries (TODO: backed by ble_event for now — empty stub)

Suspend device instance

List supplier bundles (optionally filter by status)

Create bundle (DRAFT)

Get bundle detail

Delete bundle (DRAFT only)

Update bundle fields (DRAFT only)

Replace apps list (full overwrite)

Archive bundle (PUBLISHED → ARCHIVED)

Replace devices list (full overwrite)

번들에 포함된 파이프라인 uuid 목록

번들 포함 파이프라인 목록 교체 (uuid 배열)

Publish bundle (DRAFT → PUBLISHED)

Get hub jobs

Retrieve paginated list of jobs for a specific hub. Requires READ permission on the hub's unit.

Get hub job details

Retrieve detailed information about a specific job including desired and result JSON payloads

Get hub job events

Retrieve time-ordered events for a specific job

Get hub logs

Retrieve log entries filtered by time range (latest first)

Get hub telemetry

Retrieve telemetry data filtered by time range (latest first)

Get consent settings

Get active consent settings for the current tenant (or pinned supplier)

Create or update consent settings

Create or update consent settings for a supplier

List action definitions for current tenant (auto-resolved supplier)

Create action definition

Create a new protocol action definition

Get action definition

Get a single action definition by ID

Delete action definition

Delete an action definition

Update action definition

Update an existing action definition

List agent releases (optionally filter by channel + active)

List agent update policies belonging to current tenant

Upsert UNIT/HUB scoped policy (tenant_uuid auto-set on UNIT scope)

List API keys

List all active API keys. Key hashes are never exposed.

Generate new API key

Creates a new API key. The raw key is returned ONCE and cannot be retrieved again.

Update API key

Update name, scopes, or rate limit of an existing API key.

Revoke API key

Deactivates an API key. The key can no longer be used for authentication.

Get tenant audit logs

Retrieve tenant-level audit logs with pagination

Get billing balance

sdx-web pass-through. Returns currentCreditCents, activeSubscription, lastInvoice.

[DEPRECATED] auto-charge settings — sdx-web으로 이동

[DEPRECATED] auto-charge settings — sdx-web으로 이동

Get current entitlement

sdx-web 구독 기반 entitlement (tier, limits, validUntil)

Get billing transactions

sdx-web pass-through. Cursor pagination by createdAt desc.

Get BLE deliveries

Retrieve paginated list of BLE deliveries filtered by unit scope and optional criteria

Get BLE events

Retrieve paginated list of BLE events filtered by unit scope and optional criteria. Raw base64 data is excluded from list view.

Get BLE event detail

Retrieve detailed information about a specific BLE event. Raw base64 data can be included with includeRaw=true parameter.

Get BLE event processing runs

Retrieve all processing runs and their actions for a specific BLE event

List consent records

List all consent records for the current tenant (or pinned supplier)

Dashboard summary — hub/device/pipeline/DLQ counts + BLE throughput & webhook success

windowMinutes (default 60, clamped 1–1440) sizes the events / delivery / BLE-in-range window. Hub online is derived from telemetry within a fixed 10-minute window.

List device catalog entries (Device models)

Create device catalog entry (deviceUuid auto-issued)

Get device catalog entry detail

Delete device catalog entry (hard delete)

Update device catalog entry

List identifier hints registered under a device

Add an identifier hint

Remove an identifier

Update label/notes on an identifier

List device protocols (optionally filter by deviceUuid)

Create device protocol entry

Get device protocol detail

Delete device protocol entry

Update device protocol entry

Get device catalog header (Device entity)

List device UI schemas (optionally filter by deviceUuid)

Create device UI schema

Get device UI schema detail

Delete device UI schema

Update device UI schema

List device versions (optionally filter by deviceUuid)

Create device version entry

Get device version detail

Delete device version entry

Update device version entry

Resolve a GH presigned S3 URL for a single asset (5-min TTL)

Latest release + filtered assets for installer / hub-os / hub-agent

현재 tenant 의 외부 엔드포인트 목록

외부 엔드포인트 등록

baseUrl host 로 domain 추출 + verify_token 발급. 등록 시점엔 domain_verified=false.

외부 엔드포인트 단건 조회

외부 엔드포인트 수정

baseUrl 이 바뀌면 domain 재계산 + domain_verified 리셋(재인증 필요). authConfig 비면 기존 ciphertext 유지.

외부 엔드포인트 삭제

도메인 소유 검증 실행

설정된 verify_method 로 DNS TXT / well-known 을 조회해 verify_token 게시 여부 확인. 성공 시 domain_verified=true.

List device manuals (optionally filter by deviceUuid)

Create device manual

Get device manual detail

Delete device manual

Update device manual

List notification settings for current user within tenant context

Upsert a single notification setting (by type+channel)

Bulk upsert notification settings

List active members + pending / historical invitations

Revoke a persona's access to this tenant

Change role of a tenant persona

Mark an invitation REVOKED (unlike a member revoke, this is idempotent)

Rotate token + resend invitation email

Invite by email (creates PENDING invitation) or grant by personaUuid

Stream BLE events

Subscribe to real-time BLE events via Server-Sent Events (SSE). **SSE Protocol:** - Content-Type: text/event-stream - Event name: `ble_event` - Heartbeat: Every 20 seconds (comment: ping) - Connection timeout: 5 minutes **Last-Event-ID Support:** - Client can send `Last-Event-ID` header with ISO-8601 timestamp - Server will stream events after that timestamp - Event IDs are ISO-8601 timestamps (receivedAt) **Permission:** - Requires unit scope (events filtered by persona's unit) - Requires READ permission (permissionCode & 1 == 1) **Testing with curl:** ```bash curl -N -H "Authorization: Bearer YOUR_TOKEN" \ http://localhost:8080/tenant/stream/ble/events ``` **Testing with EventSource (JavaScript):** ```javascript const eventSource = new EventSource('/tenant/stream/ble/events', { headers: { Authorization: 'Bearer YOUR_TOKEN' } }); eventSource.addEventListener('ble_event', (event) => { const data = JSON.parse(event.data); console.log('BLE event:', data); }); eventSource.onerror = (error) => { console.error('SSE error:', error); }; ```

Stream hub job events

Subscribe to real-time hub job events via Server-Sent Events (SSE). **SSE Protocol:** - Content-Type: text/event-stream - Event name: `hub_job_event` - Heartbeat: Every 20 seconds (comment: ping) - Connection timeout: 5 minutes **Last-Event-ID Support:** - Client can send `Last-Event-ID` header with ISO-8601 timestamp - Server will stream events after that timestamp - Event IDs are ISO-8601 timestamps (receivedAt) **Permission:** - Requires unit scope (persona's unit must match hub's unit) - Requires READ permission (permissionCode & 1 == 1) **Testing with curl:** ```bash curl -N -H "Authorization: Bearer YOUR_TOKEN" \ http://localhost:8080/tenant/stream/hubs/{hubUuid}/jobs ``` **Testing with EventSource (JavaScript):** ```javascript const eventSource = new EventSource('/tenant/stream/hubs/{hubUuid}/jobs', { headers: { Authorization: 'Bearer YOUR_TOKEN' } }); eventSource.addEventListener('hub_job_event', (event) => { const data = JSON.parse(event.data); console.log('Job event:', data); }); ```

Stream hub logs

Subscribe to real-time hub logs via Server-Sent Events (SSE). **SSE Protocol:** - Content-Type: text/event-stream - Event name: `hub_log` - Heartbeat: Every 20 seconds (comment: ping) - Connection timeout: 5 minutes **Last-Event-ID Support:** - Client can send `Last-Event-ID` header with ISO-8601 timestamp - Server will stream logs after that timestamp - Event IDs are ISO-8601 timestamps (receivedAt) **Permission:** - Requires unit scope (persona's unit must match hub's unit) - Requires READ permission (permissionCode & 1 == 1) **Testing with curl:** ```bash curl -N -H "Authorization: Bearer YOUR_TOKEN" \ http://localhost:8080/tenant/stream/hubs/{hubUuid}/logs ```

현재 tenant의 OAuth config 조회 (없으면 404)

secret 값은 응답에 노출되지 않음. registrationSharedSecretSet 플래그로 존재 여부만.

UPSERT — 즉시 등록 또는 (require-approval=true일 때) 승인 큐 적재

client_secret + registration_shared_secret은 plaintext로 받아 즉시 AES-GCM 암호화 저장. 응답에 secret 미노출.

현재 tenant의 OAuth config 삭제

List my accessible tenants

Create a new tenant under my current sdx unit

Soft-delete tenant (OWNER only)

Update tenant name (ADMIN+)

List tenant members (any access)

Grant access (ADMIN+; OWNER for OWNER role)

Revoke access (ADMIN+; last OWNER protected)

Initiate ownership transfer (current OWNER)

Tenant test endpoint

Test endpoint that requires JWT authentication

이전 요청 승인 (받는 unit의 멤버 persona)

이전 요청 취소 (요청자 본인 또는 OWNER)

이전 요청 거부 (받는 unit의 멤버 persona)

받은 PENDING 이전 요청 (현재 persona의 unit으로 향한)

보낸 PENDING 이전 요청 (현재 persona의 unit에서 발신)

Test unit boundary enforcement

Test endpoint that verifies persona belongs to specified unit

List action definitions for a supplier

Returns all action definitions for the specified supplier

Get action definition

Get a single action definition by ID

List PUBLISHED bundles

현재 사용자 기준 link 상태 함께 반환

Get bundle catalog detail

List consent records

List all consent records for current user

Grant consent

Grant consent for a supplier and consent type

Withdraw consent

Withdraw a previously granted consent

Get retention settings

Get retention settings for a consent record

Update retention period

Update retention period for a consent record

device_ui invoke 실행

hubUuid 소유권 검증 → supplier resolve → 인증된 external_endpoint 로 프록시 호출.

허브-device 의 device_ui setup 스키마 조회

device_ui 미저작 시 404 → 앱은 legacy step-runner 로 fallback.

List user's devices

List all devices from units where user has a persona

Get device detail

Get device detail by instance ID

Send control command

Send a control command to a device

Get sensor data

Get sensor data for a device with optional time range

List hubs

List all hubs owned by current user

Get hub detail

Get hub detail by UUID

List notifications

List notifications for current user (paginated)

Mark as read

Mark a notification as read

Get profile

Get current user profile

Update profile

Update current user profile (nickname, etc.)

Begin OAuth authorize flow

state + PKCE INSERT 후 외부 브라우저로 열 authorize URL 반환. 사용자 계정 연결은 hub와 무관 — hub/device 단위 권한은 별도 모델로 처리.

List my active supplier links

supplier_uuid 쿼리 시 그 supplier의 active link만 (n:1로 여러 개 가능)

Revoke supplier link

supplier revoke_url 호출 + 로컬 soft-revoke

Get fresh access token

만료 5분 이내면 자동 refresh 후 반환. step.configJson.external_submit_url 호출 직전에 사용.

Get consent preview (no secret)

supplier가 required로 등록되어 있으면 consent_text/scope/userinfo_url 반환