Devices & Doors API

Manage IoT devices (Raspberry Pi), configure doors, and control physical access. Devices communicate via HTTPS polling with device key authentication.

Device Endpoints

POST

/devices/activate

Activate a device with a one-time activation code

POST

/devices/{deviceId}/heartbeat

Send device health data and receive pending commands

GET

/devices/{deviceId}/commands

Poll for pending commands (backup to heartbeat)

PATCH

/devices/{deviceId}/commands/{commandId}

Report command execution result

POST

/devices/{deviceId}/access-check

Verify QR/SMS token and get unlock instruction

GET

/devices/{deviceId}/config

Get full device configuration (doors, GPIO, rules)

Device Authentication

Devices authenticate with a device key (prefixed booqr_dk_). The key is obtained during the activation flow and must be stored securely on the device.

Activation Flow

When a device is registered in the admin dashboard, an activation code is generated. The Raspberry Pi sends this code to activate and receive its device key.

Requestbash

curl -X POST \
  "https://your-domain.booqr.nl/api/devices/activate" \
  -H "Content-Type: application/json" \
  -d '{
    "activation_code": "a1b2c3d4e5f6...",
    "serial": "RPi-001",
    "firmware_version": "1.0.0"
  }'

Response 200json

{
  "device_id": "uuid",
  "device_key": "booqr_dk_abcd1234_...",
  "message": "Device activated. Store the key securely — it will not be shown again."
}

Heartbeat

Devices send heartbeats every 15 seconds with health telemetry. The response includes any pending commands, so the device doesn't need to poll separately.

Requestbash

curl -X POST \
  "https://your-domain.booqr.nl/api/devices/{deviceId}/heartbeat" \
  -H "Authorization: Bearer booqr_dk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "cpu_percent": 42,
    "memory_percent": 61,
    "wifi_signal_dbm": -52,
    "door_states": {
      "door-uuid-1": "locked",
      "door-uuid-2": "unlocked"
    }
  }'

Response 200json

{
  "status": "ok",
  "pending_commands": [
    {
      "id": "cmd-uuid",
      "type": "unlock",
      "payload": { "gpio_pin": 17, "duration_seconds": 10 },
      "expires_at": "2026-02-16T12:05:00Z"
    }
  ]
}

Access Check (QR Scan)

When a guest scans a QR code at a door, the device sends the token to this endpoint. The platform verifies the token, checks the booking, resolves door behavior, and returns an unlock instruction.

Requestbash

curl -X POST \
  "https://your-domain.booqr.nl/api/devices/{deviceId}/access-check" \
  -H "Authorization: Bearer booqr_dk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "doorId": "door-uuid"
  }'

Response 200json

{
  "allowed": true,
  "behavior": "unlock_per_scan",
  "unlockDurationSeconds": 10
}

Denied Response

When access is denied, the response includes a reason:

Requestjson

// Response when access is denied

Response 200json

{
  "allowed": false,
  "reason": "outside_booking_window"
}

Reason	Description
`invalid_token`	Token is malformed or expired
`booking_not_confirmed`	Booking exists but is not CONFIRMED
`outside_booking_window`	Current time is outside the booking start/end
`door_not_mapped_to_object`	This door doesn't serve the booked object