Device Setup Guide

Quick Start

1

Get Your Group UUID

Contact your system administrator to obtain your Group UUID. This is required for device registration.

2

Register Your Device

Make a POST request to /api/devices/register with your device information and Group UUID.

3

Wait for Approval

Your device will be in "pending" status until an administrator approves it. You'll receive an API key upon approval.

4

Start Sending Heartbeats

Once approved, use your API key to send periodic heartbeats and poll for commands.

Device Configuration

Configure your device client with the following settings:

Server URL

https://www.weblockr.app

Registration Endpoint

/api/devices/register

Heartbeat Endpoint

/api/devices/:deviceId/heartbeat

Commands Endpoint

/api/devices/:deviceId/commands

Heartbeat Interval

30 seconds (recommended)

Command Poll Interval

30 seconds (recommended)

Registration Example

Here's a complete example of how to register a device:

JavaScript / Node.js

const response = await fetch('https://www.weblockr.app/api/devices/register', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-CSRF-Token': document.querySelector('meta[name="csrf-token"]')?.content },
  body: JSON.stringify({
    deviceId: 'UNIQUE-DEVICE-ID',
    groupUuid: 'YOUR-GROUP-UUID',
    deviceName: 'My Kiosk Device',
    version: '1.0.0',
    operatingSystem: 'Windows 11',
    ipAddress: '192.168.1.100',
    macAddress: 'AA:BB:CC:DD:EE:FF',
    systemInfo: {
      cpuType: 'Intel Core i7',
      osName: 'Windows 11 Pro',
      ramGB: 16,
      hddGB: 512,
      gpuName: 'NVIDIA GeForce RTX'
    }
  })
});

const data = await response.json();
console.log(data);
// Response: { status: 'pending', message: '...' }
// or: { status: 'active', apiKey: '...', message: '...' }

Python

import requests

response = requests.post(
    'https://www.weblockr.app/api/devices/register',
    json={
        'deviceId': 'UNIQUE-DEVICE-ID',
        'groupUuid': 'YOUR-GROUP-UUID',
        'deviceName': 'My Kiosk Device',
        'version': '1.0.0',
        'operatingSystem': 'Linux',
        'ipAddress': '192.168.1.100',
        'systemInfo': {
            'cpuType': 'Intel Core i7',
            'osName': 'Ubuntu 22.04',
            'ramGB': 16,
            'hddGB': 512
        }
    }
)

data = response.json()
print(data)

C# / .NET

using System.Net.Http.Json;

var client = new HttpClient();
var response = await client.PostAsJsonAsync(
    "https://www.weblockr.app/api/devices/register",
    new {
        deviceId = "UNIQUE-DEVICE-ID",
        groupUuid = "YOUR-GROUP-UUID",
        deviceName = "My Kiosk Device",
        version = "1.0.0",
        operatingSystem = "Windows 11",
        ipAddress = "192.168.1.100",
        systemInfo = new {
            cpuType = "Intel Core i7",
            osName = "Windows 11",
            ramGB = 16,
            hddGB = 512
        }
    }
);

var data = await response.Content.ReadFromJsonAsync();

Heartbeat Example

After approval, send regular heartbeats to keep your device active:

JavaScript

// Send heartbeat every 30 seconds
setInterval(async () => {
  const response = await fetch(
    'https://www.weblockr.app/api/devices/YOUR-DEVICE-ID/heartbeat',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR-API-KEY'
      },
      body: JSON.stringify({
        version: '1.0.0',
        pcName: 'KIOSK-01',
        ipAddress: '192.168.1.100',
        url: 'https://example.com',
        uptime: 123456,
        metrics: {
          cpuPercent: 45.2,
          memoryPercent: 62.1,
          memoryUsedMB: 8192,
          memoryTotalMB: 16384,
          diskFreeGB: 256,
          diskTotalGB: 512
        }
      })
    }
  );
  
  const data = await response.json();
  console.log('Heartbeat sent:', data);
}, 30000);

Important Notes

Device ID: Must be unique and 8-64 alphanumeric characters
Group UUID: Must be valid and active
API Key Storage: Store your API key securely after approval
Heartbeat Timing: Send heartbeats every 30 seconds to maintain active status
Command Polling: Check for commands regularly (every 30-60 seconds)
Error Handling: Implement retry logic for failed requests

Troubleshooting

Q: Registration returns "Invalid group UUID"

A: Verify your Group UUID with your administrator. Ensure the group is active.

Q: Device stuck in "pending" status

A: Contact your administrator to approve the device in the dashboard.

Q: Heartbeat returns 401 Unauthorized

A: Check that you're including the correct API key in the X-API-Key header.

Q: Device shows as offline

A: Ensure heartbeats are being sent every 30 seconds and check network connectivity.

API Documentation Server Status Health Check Admin Login