External Integrations

Screen-First Device Binding

End-to-end TV provisioning and binding flow based on current API behavior.

Binding Sequence

  1. Step 1: Create venue and screen

    Screen is created in provisioning state and scoped to a tenant.

  2. Step 2: Generate provisioning code

    POST /v1/devices/provisioning-codes returns an 8-char code with ~15 minute expiry.

  3. Step 3: Enter code in TV app

    TV app sends pairingCode + deviceInfo to POST /devices/register.

  4. Step 4: Register and bind device

    API validates code, binds to screen, issues one-time dak_ apiKey, activates screen.

  5. Step 5: Runtime polling and playback

    TV calls playlist/config/events endpoints with Authorization: Bearer <dak_...>.

  6. Step 6: Re-provision when needed

    POST /v1/devices/:id/revoke suspends device + revokes active device key; screen returns to provisioning.

Validation Constraints

Pairing code: exactly 8 chars, uppercase alphanumeric (^[A-Z0-9]+$).

MAC address: XX:XX:XX:XX:XX:XX or XX-XX-XX-XX-XX-XX.

IP address: must pass IPv4/IPv6 validation.

Provisioning code TTL: generated for ~15 minutes.

Registration Request Example

POST /devices/register
Content-Type: application/json

{
  "pairingCode": "ABCD1234",
  "deviceInfo": {
    "manufacturer": "Sony",
    "model": "BRAVIA-55",
    "osVersion": "Android 12",
    "appVersion": "1.0.0",
    "macAddress": "00:11:22:33:44:55",
    "ipAddress": "192.168.1.100",
    "deviceName": "Lobby Screen",
    "locationHint": "Front desk"
  }
}

Registration Success Shape

HTTP/1.1 201 Created

{
  "deviceId": "<uuid>",
  "screenId": "<uuid>",
  "apiKey": "dak_<one_time_secret>",
  "tenantId": "<tenant_id>",
  "config": {
    "syncIntervalMinutes": 5,
    "heartbeatIntervalMinutes": 1,
    "cachePolicy": {
      "maxSizeGB": 10,
      "retentionDays": 7
    }
  }
}

Important: the device apiKey is returned once. Persist securely on device.

Operational Actions

Poll provisioning status

GET /v1/devices/provisioning-codes/ABCD1234/status

Revoke and re-provision

POST /v1/devices/<device_id>/revoke
Content-Type: application/json

{ "reason": "Replaced hardware" }

Revocation suspends the device, revokes active device keys, and returns the screen to provisioning.