Devices

A device is a named entity that can be linked to an API key and appears as device_id on GPS data. Devices allow you to distinguish between multiple GPS senders and associate GPS tracks with trips.

Device Fields

Field	Type	Description
id	UUID	Device ID
name	string	Human-readable name
description	string?	Optional description
device_type	string?	Free-text type label (e.g. "Truck", "Router")
is_active	bool	Inactive devices are ignored during resolution
created_at	timestamp	Creation time
updated_at	timestamp	Last update time

Create/Update Input Fields

Field	Type	Context	Description
name	string	create (required), update	Human-readable name
description	string?	create, update	Optional description
device_type	string?	create, update	Free-text type label (e.g. "Truck", "Router")
is_active	bool?	update only	Inactive devices are ignored during resolution
api_key_id	UUID?	create, update	Links the device to an API key. When set, the API key's device_id is updated to point to this device. This enables automatic device-ID resolution on GPS POST -- any GPS point ingested with that API key automatically inherits this device.

REST Endpoints

Method	Path	Permission	Description
GET	/v1/devices	devices:read	List devices (paginated)
GET	/v1/devices/{id}	devices:read	Get device by ID
POST	/v1/devices	devices:write	Create device
PATCH	/v1/devices/{id}	devices:write	Update device
DELETE	/v1/devices/{id}	devices:delete	Delete device

GraphQL

Queries:

• devices(page, limit) → PaginatedDevices
• device(id) → GqlDevice

Mutations:

• createDevice(input) → GqlDevice
• updateDevice(id, input) → GqlDevice
• deleteDevice(id) → Boolean

The GqlDevice type includes an apiKey field (nullable) resolved via reverse lookup on the ApiKey table.

Create Device

POST /v1/devices
{
  "name": "Peplink Router 1",
  "description": "On truck Mannheim-01",
  "device_type": "Router",
  "api_key_id": "optional-api-key-uuid"
}

Passing api_key_id during creation links the device to the specified API key immediately. You can also set or change this later via update.

Link API Key to Device

Assign an API key to a device by updating the API key:

PATCH /v1/api-keys/{keyId}
{
  "device_id": "<device-uuid>"
}

Remove the link by setting "device_id": null.

Device-ID Resolution

When a GPS point is ingested via POST /v1/gps, the API resolves a device_id in order:

1. X-Device-ID header — if present, the API validates the device exists and is_active = true. Any active device is accepted (no ownership check — GPS is system-internal).
2. API key device_id — the authenticated API key's linked device.
3. NULL — stored without a device reference if neither source provides one.

Deletion Behaviour

• Deleting a device sets ApiKey.device_id = NULL (via ON DELETE SET NULL).
• Deleting a device sets Trip.device_id = NULL (via ON DELETE SET NULL).
• Historical GPS data retains the orphaned device_id value — this is intentional for audit continuity (no foreign key across databases).
• Deleting a device does not delete any GPS data.

RBAC Permissions

Permission	Description
devices:read	View devices
devices:write	Create and update devices
devices:delete	Delete devices