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)

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

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)

List hubs

List all hubs for current unit with READ permission check

Get hub detail

Get hub detail with READ permission check

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 wizard steps + submission state for the hub

Submit (or skip) one wizard step

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 provisioning steps for current tenant

Uses X-Tenant-UUID header to scope the list

Create provisioning step

Create a new provisioning step for a supplier

Update provisioning step

Update an existing provisioning step

Delete provisioning step

Delete a provisioning step

List provisioning steps

List all provisioning steps for a supplier

Reorder provisioning steps

Reorder provisioning steps for a supplier

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)

Publish bundle (DRAFT → PUBLISHED)

Replace provisioning steps list (full overwrite)

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)

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

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 members of current tenant

Revoke persona access from tenant

Change role of a tenant persona

Invite a persona (create via sdx-oauth or grant existing)

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 ```

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 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

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.)

Get provisioning steps

Get supplier's custom provisioning steps