> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Link kiosk device

> Poll a tablet device code until the dashboard claims it, then return store scope, settings, payments, and overrides.

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.

> [!NOTE]
>
> 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](https://firespark.cloud/docs/guides/channels/kiosk.md).

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

```bash theme={null}
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](https://firespark.cloud/docs/storefront-api/kiosk/devices/me/post.md) 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.