Link kiosk device - Fire spark

The tablet POSTs a hardware-stable device_code and a device_secret it holds locally. Until someone claims that code in the dashboard (Devices → Link device), the API returns 404 with DEVICE_NOT_LINKED. After the claim, the first successful call binds the secret to that row. Later calls return the linked config.

These kiosk routes do not use a customer access token. Send device_code and device_secret in the JSON body. Keep the secret on the tablet — it never goes to the dashboard.

The code is unique per merchant. Derive it from the tablet hardware ID (SHA-1, first 8 hex digits, then base36) so a reinstall keeps the same code. See Set up kiosks.

Request body

Field	Required	Type	Description
`device_code`	Yes	string	At least 8 characters. Trimmed and uppercased.
`device_secret`	Yes	string	Tablet secret. First writer wins if two tablets poll the same unbound code.

Request

curl -X POST "https://firespark.cloud/api/storefront/v1/kiosk/devices/link" \
  -H "Content-Type: application/json" \
  -d '{"device_code":"A1B2C3D4","device_secret":"ksec_9f86d081884c7d659a2feaa0c55ad015"}'

Response

The body is { data: KioskDeviceConfig }.

Field	Description
`device.uid`	Internal device id. Use it on heartbeat and later kiosk calls.
`device.id`	External device id.
`device.alias`	Label set when the dashboard claimed the code.
`scope.store_id`	Store assigned at claim, or `null`.
`scope.channel_id`	Kiosk channel id.
`settings.idle_timeout_seconds`	Session idle timeout from channel settings.
`settings.idle_warning_seconds`	Idle warning before reset.
`settings.offline_after_minutes`	How long without a heartbeat before the dashboard marks the tablet offline.
`overrides.disabled_payment_ids`	Payment method ids this tablet must hide.
`payments`	Storefront payment catalog for the device store and channel. Secrets are stripped.

Errors

Status	When
`404`	Code is not claimed. Body includes `code: "DEVICE_NOT_LINKED"`. Keep polling.
`401`	A claimed device exists for this code, but the secret does not match.
`403`	A row exists for this code and is `DISABLED`.
`400`	Body failed validation.